3.1.4.21 rpc_ACHandleToFormatName (Opnum 26)

  • Article

A client calls the rpc_ACHandleToFormatName method to retrieve a format name for a queue handle.

 HRESULT rpc_ACHandleToFormatName(
   [in] RPC_QUEUE_HANDLE hQueue,
   [in, range(0, 524288)] DWORD dwFormatNameRPCBufferLen,
   [in, out, unique, size_is(dwFormatNameRPCBufferLen), length_is(dwFormatNameRPCBufferLen)] 
     WCHAR* lpwcsFormatName,
   [in, out] DWORD* pdwLength
 );

hQueue:  MUST be an RPC_QUEUE_HANDLE (section 2.2.1.1.2) acquired from the phQueue parameter of rpc_QMOpenQueueInternal (section 3.1.4.17). Prior to this method being invoked, the queue MUST NOT have been deleted, and the queue handle MUST NOT have been closed.

dwFormatNameRPCBufferLen:  Length of the buffer (in Unicode characters) provided for the lpwcsFormatName parameter.

lpwcsFormatName:  Pointer to a Unicode character buffer into which the server writes the format name (as specified in [MS-MQMQ]) for the queue identified by the hQueue parameter. The character buffer MUST be null-terminated by the server prior to returning, even if the provided buffer is not large enough to contain the entire format name string. Can be NULL if dwFormatNameRPCBufferLen is 0x00000000. MUST NOT be NULL if dwFormatNameRPCBufferLen is nonzero.

pdwLength:  On input, the maximum number of Unicode characters to write to the lpwcsFormatName buffer. This value MUST be equal to the dwFormatNameRPCBufferLen parameter. On return, the server MUST update the value of this parameter to indicate the complete length of the format name string for the queue identified by hQueue, without regard for the size of the provided buffer.

Return Values:  If the provided buffer is long enough to contain the null-terminated format name for the queue identified by hQueue, the server MUST take the following actions:

  • Copy the null-terminated format name into the lpwcsFormatName buffer.

  • Set pdwLength to the length (in Unicode characters) of the format name, including the terminating null character.

  • Return MQ_OK (0x00000000).

If the provided buffer is too small to contain the complete format name for the queue identified by hQueue (including the terminating null character), the server MUST take the following actions:

  • If the buffer length (indicated by pdwLength) is greater than 0x00000000, and if lpwcsFormatName is non-NULL, copy the format name to the lpwcsFormatName buffer, truncated to fit the length indicated by the input value for pdwLength. The string MUST be null-terminated post-truncation.

  • Set pdwLength to the length of the untruncated format name, including the terminating null character.

  • Take no further action and return MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL (0xc00e001f).

If input parameter values violate constraints specified above, the server MUST take no further action and return a failure HRESULT.

If any other error occurs, the server MUST return a failure HRESULT,<57> and the client MUST treat all other failure HRESULTs identically. Additionally, if any other failure HRESULT is returned, the client MUST disregard all out-parameter values.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

This method is invoked at the dynamically assigned endpoint returned by the R_QMGetRTQMServerPort (section 3.1.4.24) method when IP_HANDSHAKE (0x00000000) or IPX_HANDSHAKE (0x00000002) is the interface specified by the fIP parameter.

 The format name to be returned to the client (using the rules defined above) is determined as follows:

  • Locate a LocalQueueContextHandle (section 3.1.1.3) ADM element instance in the server's iLocalQueueContextHandleTable (section 3.1.1.2) where the value of the Handle attribute of the LocalQueueContextHandle ADM element instance equals hQueue.

  • If such a LocalQueueContextHandle ADM element instance exists:

    • Declare iLocatedLocalQueueContextHandle and set it to a reference to the located LocalQueueContextHandle ADM element instance.

    • The format name to be returned to the client is iLocatedLocalQueueContextHandle.OpenQueueDescriptorReference.FormatName.

  • Else:

    • Locate a RemoteQueueProxyHandle (section 3.1.1.5) ADM element instance in the server's iRemoteQueueProxyHandleTable (section 3.1.1.4) where the value of the Handle attribute of the RemoteQueueProxyHandle ADM element instance equals hQueue.

    • If no such RemoteQueueProxyHandle ADM element instance exists, take no further action and return a failure HRESULT.

    • Declare iLocatedRemoteQueueProxyHandle and set it to a reference to the located RemoteQueueProxyHandle ADM element instance.

    • The format name to be returned to the client is iLocatedRemoteQueueProxyHandle.FormatName.