Share via

3.1.4.18 rpc_ACCloseHandle (Opnum 20)

  • Article

A client calls the rpc_ACCloseHandle method to close context handles acquired from rpc_QMOpenQueueInternal (section 3.1.4.17).

 HRESULT rpc_ACCloseHandle(
   [in, out] RPC_QUEUE_HANDLE* phQueue
 );

phQueue:  MUST be a context handle acquired from the phQueue out-parameter of the rpc_QMOpenQueueInternal method. On success, the server MUST set this parameter to NULL.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT,<52> 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: 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.

When processing this call, the server MUST:

  • 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 phQueue.

  • If such a LocalQueueContextHandle ADM element instance exists:

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

    • Generate a Close Queue ([MS-MQDMPR] section 3.1.7.1.2) event with the following argument value:

      • iQueueDesc := iLocatedLocalQueueContextHandle.OpenQueueDescriptorReference

    • Delete iLocatedLocalQueueContextHandle from the server's iLocalQueueContextHandleTable.

    • Set phQueue to NULL.

    • Take no further action and return MQ_OK (0x00000000).

  • 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 phQueue.

    • 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.

    • Invoke the RemoteQMCloseQueue method of the qm2qm RPC interface as specified in [MS-MQQP] section 3.1.4.4 using the binding handle in iLocatedRemoteQueueProxyHandle.RemoteBindingHandle and the following parameter value:

      • pphContext := iLocatedRemoteQueueProxyHandle.RemoteHandle

    • Upon completion of the RemoteQMCloseQueue method, successful or not, dispose of the iLocatedRemoteQueueProxyHandle.RemoteBindingHandle as appropriate.

      • Note: This method SHOULD<53> start a parallel process to perform the above operations and return S_OK without waiting for the process to complete. Since S_OK is returned to the client without regard for the activities in the parallel process, failures that occur in the parallel process will not be conveyed to the client, which will delay reclamation of resources in the [MS-MQQP] server.

    • Delete iLocatedRemoteQueueProxyHandle from iRemoteQueueProxyHandleTable.

    • Set phQueue to NULL.

    • Return MQ_OK (0x00000000).