3.1.4.15 R_EndTransactionalReceive (Opnum 15)

The client MUST invoke the R_EndTransactionalReceive method to advise the server that the message packet returned by the R_StartTransactionalReceive (Opnum 13) (section 3.1.4.13) method has been received by the client.<31>

The combination of the R_StartTransactionalReceive method and the positive acknowledgment of the R_EndTransactionalReceive 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.

 HRESULT R_EndTransactionalReceive(
   [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, as specified in [MS-RPCE] section 2.

phContext: MUST be set by the client to the QUEUE_CONTEXT_HANDLE_NOSERIALIZE structure used in the corresponding call to the R_StartTransactionalReceive 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_StartTransactionalReceive method request. The following table lists possible values.

dwRequestId: MUST be set by the client to the same value as the dwRequestId  parameter in the corresponding call to the R_StartTransactionalReceive method. This parameter acts as an identifier to correlate an R_EndTransactionalReceive method call to 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 do the following:

• 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 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 fMessage by searching queueDesc.QueueReference.MessagePositionCollection for a MessagePosition ADM element instance fMessagePosition where fMessagePosition.MessageReference.LookupIdentifier equals the LookupIdentifier ADM attribute of the PendingRequestEntry ADM element instance referenced by {phContext, dwRequestId}. The corresponding Message ADM element instance fMessage is referenced by the MessageReference ADM attribute of the matching MessagePosition ADM element instance fMessagePosition.

• 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 := fMessage.

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

  • iTransactional := True.

• Return rStatus.