Share via

3.1.4.9 R_EndReceive (Opnum 9)

  • Article

The client MUST invoke the R_EndReceive method to advise the server that the message packet returned by the R_StartReceive (Opnum 7) (section 3.1.4.7) method has been received.

The combination of the R_StartReceive method and the positive acknowledgment of the R_EndReceive method ensures that a message packet is not lost in transit from the server to the client due to a network outage during the call sequence.

Note that a call to the R_StartTransactionalReceive (Opnum 13) (section 3.1.4.13) method is ended through a corresponding call to the R_EndTransactionalReceive (Opnum 15) (section 3.1.4.15) method, not through a call to this method.

 HRESULT R_EndReceive(
   [in] handle_t hBind,
   [in] QUEUE_CONTEXT_HANDLE_NOSERIALIZE phContext,
   [in, range(1,2)] DWORD dwAck,
   [in] DWORD dwRequestId
 );

hBind: MUST be an RPC binding handle parameter for use by the server=, 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. 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 closed through a prior call to the R_CloseQueue (Opnum 3) (section 3.1.4.3) method. This value MUST NOT be NULL.

dwAck: MUST be set to an Acknowledgment (ACK) or a Negative Acknowledgment (NACK) for the message packet received from the server in an R_StartReceive method request. The following table lists possible values.

Value

Meaning

RR_ACK

0x00000002

The client acknowledges that the message packet was received successfully.

The server MUST remove the message from the queue and make it unavailable for subsequent consumption.

RR_NACK

0x00000001

The client acknowledges that the message packet was not received successfully.

The server MUST keep the message in the queue and make it available for subsequent consumption.

dwRequestId: MUST be set by the client to the same value as the dwRequestId parameter in the corresponding call to the R_StartReceive method. This parameter acts as an identifier to correlate an R_EndReceive method call to an R_StartReceive 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 [MS-RPCE].

When processing this call, the server MUST:

  • If the queue referenced by the phContext parameter handle has no PendingRequestEntry (section 3.1.1.2) ADM element instance in its PendingRequestTable (section 3.1.1.3) ADM element, return MQ_ERROR_INVALID_HANDLE (0xC00E0007).

  • Look up the PendingRequestEntry ADM element instance referenced by the {phContext, dwRequestId} key pair in the PendingRequestTable ADM element. If a match is not found on the {phContext, dwRequestId} key pair, return MQ_ERROR_INVALID_PARAMETER (0xC00E0006). Otherwise, remove the PendingRequestEntry ADM element instance from the PendingRequestTable ADM element, and cancel the associated instance of the Pending Request Cleanup Timer (section 3.1.2.2).

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

  • Find the corresponding Message ADM element instance by searching OpenQueueDescriptor.QueueReference.MessagePositionCollection for a MessagePosition ADM element instance where MessagePosition.MessageReference.LookupIdentifier equals the LookupIdentifier ADM attribute of the PendingRequestEntry ADM element instance referenced by {phContext, dwRequestId}. The corresponding Message ADM element instance is referred to by the MessageReference ADM attribute of the MessagePosition ADM element instance where the match was found.

  • If not found, return MQ_ERROR_MESSAGE_NOT_FOUND (0xC00E0088).

  • Set rStatus to the result of a Dequeue Message End ([MS-MQDMPR] section 3.1.7.1.12) event with the following inputs:

    • iQueueDesc := queueDesc.

    • iMessage := The found Message ADM element instance.

    • iDeleteMessage := True if the dwAck parameter is equal to RR_ACK and false if the dwAck parameter is equal to RR_NACK.

  • Return rStatus.