Share via

3.1.4.6 RemoteQMCancelReceive (Opnum 5)

  • Article

The RemoteQMCancelReceive method cancels a pending call to RemoteQMStartReceive and provides a way for the client to cancel a blocked request.

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

  • RemoteQMOpenQueue

  • RemoteQMStartReceive or RemoteQMStartReceive2

     HRESULT RemoteQMCancelReceive(
   [in] handle_t hBind,
   [in] DWORD hQueue,
   [in] DWORD pQueue,
   [in] DWORD dwRequestID
 );

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

hQueue:  Queue identifier to cancel receive. Its value is validated in the method's processing rules.

pQueue:  Queue descriptor to cancel receive. Its value is validated in the method's processing rules.

dwRequestID: A unique value that identifies a pending remote read operation.

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 (0xC00E0001)

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

MQ_ERROR_INVALID_HANDLE (0xC00E0007)

STATUS_NOT_FOUND (0xC0000225)

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:

  • Return MQ_ERROR_INVALID_PARAMETER (0xc00e0006) if pQueue is equal to zero or not equal to hQueue. <17>

  • Find the subset of RemoteReadEntry elements in rRemoteReadEntryCollection where hQueue = RemoteReadEntry.OpenQueueDescriptorHandle.

  • If no such entry is found, return MQ_ERROR_INVALID_HANDLE(0xc00e0007).

  • Find RemoteReadEntry from the collection preceding where RemoteReadEntry.RequestId=dwRequestID.

  • If no such entry is found, return MQ_ERROR(0xC00E0001).

  • For each queue in the QueueManager.QueueCollection:

    • For each OpenQueueDescriptor in Queue.OpenQueueDescriptorCollection:

      • Find the OpenQueueDescriptor where OpenQueueDescriptor.Handle=RemoteReadEntry.OpenQueueDescriptorHandle.

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

    • iQueue:=QueueReference member of the OpenQueueDescriptor obtained earlier.

    • iTag:= dwRequestID.

    • iStatus:= MQ_INFORMATION_REMOTE_CANCELED_BY_CLIENT (0x400E03E9).

  • Delete the RemoteReadEntry.

  • Return rStatus of the Cancel Waiting Message Read Request event.