3.1.4.2 RemoteQMEndReceive (Opnum 1)

  • Article

The client MUST invoke the RemoteQMEndReceive method to advise the server that the message packet returned by the RemoteQMStartReceive, RemoteQMStartReceive2, or RemoteQMStartReceiveByLookupId method has been received.

The combination of the RemoteQMStartReceive, RemoteQMStartReceive2, or RemoteQMStartReceiveByLookupId method and the positive acknowledgment of the RemoteQMEndReceive 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.

Before calling this method, the following methods MUST be called:

  • RemoteQMOpenQueue

  • RemoteQMStartReceive, RemoteQMStartReceive2, or RemoteQMStartReceiveByLookupId

     HRESULT RemoteQMEndReceive(
   [in] handle_t hBind,
   [in, out] PCTX_REMOTEREAD_HANDLE_TYPE* pphContext,
   [in, range(1, 2)] DWORD dwAck
 );

hBind: MUST be an RPC binding handle parameter for use by the server, as specified in [MS-RPCE] section 2.

pphContext: A pointer to a context handle of a pending remote read operation.

dwAck: An ACK or NACK about the status of the message packet of the pending remote read operation.

Value

Meaning

RR_NACK

0x00000001

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

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

RR_ACK

0x00000002

The client acknowledges that the message packet was delivered successfully.

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

Return Values: The method MUST return MQ_OK (0x00000000) on success; otherwise, it MUST return a failure HRESULT, and the client MUST treat all failure HRESULTs identically.

MQ_OK (0x00000000)

MQ_ERROR_INVALID_HANDLE (0xC00E0007)

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

MQ_ERROR_TRANSACTION_SEQUENCE (0xC00E0051)

Exceptions Thrown: No exceptions are thrown except those thrown by the underlying RPC protocol, [MS-RPCE].

When processing this call, the server MUST:

  • Return MQ_ERROR_INVALID_HANDLE (0xc00e0007) if pphContext is NULL.

  • Use pphContext as RemoteReadEntry.

  • The server MAY search rRemoteReadEntryCollection where OpenQueueDescriptorHandle = RemoteReadEntry.OpenQueueDescriptorHandle and return MQ_ERROR_INVALID_PARAMETER (0xC00E0006) if the OpenQueueDescriptorHandle is not found.<11>

  • Within the OpenQueueDescriptorCollection properties of all queues present in QueueManager.QueueCollection, find the OpenQueueDescriptor where OpenQueueDescriptor.Handle = RemoteReadEntry.OpenQueueDescriptorHandle and generate a Dequeue Message End event with the following inputs:

    • iQueueDesc:= reference to OpenQueueDescriptor obtained.

    • iMessage:= RemoteReadEntry.UserMessagePacket.

    • iDeleteMessage:= true if dwAck is equal to RR_ACK, and false if dwAck is equal to RR_NACK.

  • Delete the RemoteReadEntry, and set pphContext to NULL.

  • Return rStatus.