Share via

3.1.4.8 R_CancelReceive (Opnum 8)

  • Article

The R_CancelReceive method cancels a pending call to the R_StartReceive (Opnum 7) (section 3.1.4.7) method or the R_StartTransactionalReceive (Opnum 13) (section 3.1.4.13) method. Each of those methods takes a time-out parameter that can cause the server to not return a response until a message becomes available or the time-out expires. The R_CancelReceive method provides a way for the client to cancel a blocked request.

 HRESULT R_CancelReceive(
   [in] handle_t hBind,
   [in] QUEUE_CONTEXT_HANDLE_NOSERIALIZE phContext,
   [in] DWORD dwRequestId
 );

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

phContext: MUST be set by the client to the QUEUE_CONTEXT_HANDLE_NOSERIALIZE (section 2.2.4.1) handle used in the corresponding call to the R_StartReceive method that is to be canceled. 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 and MUST NOT have been previously closed through a call to the R_CloseQueue (Opnum 3) (section 3.1.4.3) method. This value MUST NOT be NULL.

dwRequestId: MUST be set by the client to the same value as the dwRequestId parameter in the corresponding call to the R_StartReceive method or the R_StartTransactionalReceive method. This parameter acts as an identifier to correlate an R_CancelReceive method call to an R_StartReceive or an R_StartTransactionalReceive method call.

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.

  • Generate a Cancel Waiting Message Read Request ([MS-MQDMPR] section 3.1.7.1.17) event with the following inputs:

    • iQueue := queueDesc.QueueReference

    • iTag := dwRequestId

  • If the Cancel Waiting Message Read Request event returns an error, return a failure HRESULT, and perform no further actions.

  • Remove the PendingRequestEntry (section 3.1.1.2) ADM element instance referenced by the {phContext, dwRequestId} key pair from the PendingRequestTable (section 3.1.1.3) ADM element.

  • Respond to the pending R_StartReceive or R_StartTransactionalReceive method request with MQ_ERROR_OPERATION_CANCELLED (0xC00E0008).