Share via

3.1.4.6 R_PurgeQueue (Opnum 6)

  • Article

The R_PurgeQueue method removes all messages from the queue.

 HRESULT R_PurgeQueue(
   [in] handle_t hBind,
   [in] QUEUE_CONTEXT_HANDLE_NOSERIALIZE phContext
 );

hBind: MUST specify an RPC binding handle parameter, as specified in [MS-RPCE] section 2.

phContext: MUST be set by the client to a QUEUE_CONTEXT_HANDLE_NOSERIALIZE (section 2.2.4.1) handle of the queue to be purged. The handle MUST have been returned by the server in the pphQueue output parameter of a prior call to the R_OpenQueue (Opnum 2) (section 3.1.4.2) method with the dwAccess parameter set to RECEIVE_ACCESS and MUST NOT have been closed through a prior call to the R_CloseQueue (Opnum 3) (section 3.1.4.3) method. This value MUST NOT be NULL.

Return Values: On success, this method MUST return MQ_OK (0x00000000).

If an error occurs, the server MUST return a failure HRESULT, and the client MUST treat all failure HRESULTs identically.

Exceptions Thrown:

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

When processing this call, the server MUST:

  • Find the corresponding OpenQueueDescriptor ADM element instance by comparing the phContext parameter with the Handle ADM attribute for all OpenQueueDescriptor ADM element instances maintained by the local QueueManager ADM element instance.

  • If not found, return a failure HRESULT, and perform no further actions. Otherwise, assign the found OpenQueueDescriptor ADM element instance to the local variable queueDesc.

  • If queueDesc.AccessType is QueueAccessType.ReceiveAccess:

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

      • iQueue := queueDesc.QueueReference

    • Return MQ_OK (0x00000000), and perform no further actions.

  • Return STATUS_ACCESS_DENIED (0xC0000022).