3.1.4.1 R_QMGetRemoteQueueName (Opnum 1)

  • Article

During the process of creating a remote cursor, a client calls the R_QMGetRemoteQueueName method to retrieve the name of the remote queue associated with a queue handle. This method is obsolete and the server SHOULD take no action and immediately raise the exception MQ_ERROR_ILLEGAL_OPERATION (0xc00e0064).<11>

 HRESULT R_QMGetRemoteQueueName(
   [in] handle_t hBind,
   [in] DWORD pQueue,
   [in, out, ptr, string] WCHAR** lplpRemoteQueueName
 );

hBind:  MUST be set to an RPC binding handle as described in [MS-RPCE] section 2.

pQueue:  MUST be a DWORD that contains a queue context value obtained from the cli_pQMQueue member of the structure returned by the rpc_ACCreateCursorEx method of the qmcomm2 interface. See section 4.4 for an example illustrating this value being obtained.

lplpRemoteQueueName:  A pointer to a buffer to receive the null-terminated name of the remote queue associated with pQueue. On input, this value MUST be NULL.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT, and the client MUST treat all failure HRESULTs identically. Additionally, if a failure HRESULT is returned, the client MUST disregard all out-parameter values.

Exceptions Thrown: This method SHOULD take no action and SHOULD immediately raise the exception MQ_ERROR_ILLEGAL_OPERATION (0xc00e0064).<12>

During the remote cursor creation sequence, the supporting server MAY indicate that the client MUST contact a remote queue manager to proceed.<13> In response, this method is called by the client to determine where to find the remote queue manager. Supporting servers SHOULD contact the remote queue manager on behalf of the client, thus eliminating the purpose of this method.<14>

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

 When processing this call, the server MUST do the following:

  • Locate the RemoteQueueProxyHandle (section 3.1.1.5) ADM element instance in the server's iRemoteQueueProxyHandleTable where the Context attribute value of the RemoteQueueProxyHandle ADM element instance equals pQueue.

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

  • Set lplpRemoteQueueName to the PathName attribute of the located RemoteQueueProxyHandle ADM element instance.

  • Return MQ_OK (0x00000000).