The rpc_ACPurgeQueue method is called by a client to purge an opened queue.

 HRESULT rpc_ACPurgeQueue(
   [in] RPC_QUEUE_HANDLE hQueue
 );

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

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT,<58> and the client MUST treat all failure HRESULTs identically.

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

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

    • iQueue := iLocatedLocalQueueContextHandle.OpenQueueDescriptorReference.QueueReference

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

  • Using the binding handle contained in iLocatedRemoteQueueProxyHandle.RemoteBindingHandle, invoke the method RemoteQMPurgeQueue of the qm2qm interface defined in [MS-MQQP] section 3.1.4.7 with the following argument value:

    • hQueue := iLocatedRemoteQueueProxyHandle.RemoteContext

  • Return the return code produced by RemoteQMPurgeQueue.