3.1.4.10 RemoteQMStartReceive2 (Opnum 9)

  • Article

The RemoteQMStartReceive2 method functions in the same way as RemoteQMStartReceive (section 3.1.4.1), except that it returns a structure that contains the SequentialId of the message.<25>

 HRESULT RemoteQMStartReceive2(
   [in] handle_t hBind,
   [out] PCTX_REMOTEREAD_HANDLE_TYPE* pphContext,
   [in, out] REMOTEREADDESC2* lpRemoteReadDesc2
 );

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

pphContext: The server MUST return a non-NULL value for this handle upon success for receive calls. This handle will be used by the client in subsequent calls to RemoteQMEndReceive (section 3.1.4.2). This handle MUST NOT be set upon failure or for peek calls. If this method returns an error, pphContext is undefined and MUST NOT be used as an argument for a call to RemoteQMEndReceive.

lpRemoteReadDesc2: A pointer to an instance of a REMOTEREADDESC2 (section 2.2.2.2) structure. The SequentialId member MUST be set to the least significant 7 bytes of the Message.LookupIdentifier ([MS-MQDMPR] section 3.1.1.12) of the message that is returned by this method.

The client MUST provide all parameters of lpRemoteReadDesc2.pRemoteReadDesc that are marked as to be set by the client in section 2.2.2.1.

The lpRemoteReadDesc2.pRemoteReadDesc.ulAction parameter MUST be one of the following values.

Value of ulAction

Meaning

MQ_ACTION_RECEIVE

0x00000000

If hCursor is nonzero, read and remove the first message available at the current cursor location walking toward the end of the queue.

If hCursor is zero, read and remove the message from the front of the queue.

MQ_ACTION_PEEK_CURRENT

0x80000000

If hCursor is nonzero, read the message at the current cursor location, but do not remove it from the queue. The cursor location does not change after the operation.

If hCursor is zero, read the message at the front of the queue, but do not remove it from the queue.

MQ_ACTION_PEEK_NEXT

0x80000001

Read the message following the message at the current cursor location, but do not remove it. The cursor location will then change to the next available message, walking toward the end of the queue.

The hCursor parameter MUST be set to a nonzero cursor handle.

The hCursor member of lpRemoteReadDesc specifies a handle to an opened cursor. A value of zero indicates that a cursor is not used for this operation.

The dwRequestID member of the lpRemoteReadDesc parameter is used in a subsequent call to RemoteQMEndReceive or RemoteQMCancelReceive to correlate that call with the call to RemoteQMStartReceive2.

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

While processing this method, the server MUST:

  • Return MQ_ERROR_INVALID_HANDLE (0xC00E0007) if lpRemoteReadDesc2 is NULL.

  • Return MQ_ERROR_INVALID_HANDLE (0xC00E0007) if lpRemoteReadDesc2.pRemoteReadDesc is NULL.

  • Return MQ_ERROR_INVALID_PARAMETER (0xC00E0006) if lpRemoteReadDesc2.pRemoteReadDesc.dwQueue is set to 0x00000000 or lpRemoteReadDesc2.pRemoteReadDesc.dwQueue is not equal to lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue.

  • The server SHOULD return MQ_ERROR_INVALID_PARAMETER (0xC00E0006) if the lpRemoteReadDesc2.pRemoteReadDesc.dwRequestID does not uniquely identify the receive request. This duplicate detection is performed by searching for a RemoteReadEntry, referred to as rRemoteReadEntry, in rRemoteReadEntryCollection such that rRemoteReadEntry.OpenQueueDescriptorHandle = lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue and rRemoteReadEntry.RequestId = lpRemoteReadDesc2.pRemoteReadDesc.dwRequestID.<26>

  • Return STATUS_INVALID_PARAMETER (0xC000000D) if lpRemoteReadDesc2.pRemoteReadDesc.hCursor is set to 0x00000000 and the lpRemoteReadDesc2.pRemoteReadDesc.ulAction is set to MQ_ACTION_PEEK_NEXT.

  • Search the rOpenQueueEntryCollection where OpenQueueEntry.OpenQueueDescriptorHandle = lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue.

  • If the OpenQueueDescriptorHandle is not found, return MQ_ERROR_INVALID_PARAMETER (0xC00E0006).

  • Find the OpenQueueDescriptor, referred to as rOpenQueueDescriptor, in the Queue.OpenQueueDescriptorCollection of each queue object in QueueManager.QueueCollection such that rOpenQueueDescriptor.Handle = lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue.

  • If lpRemoteReadDesc2.pRemoteReadDesc.hCursor is not 0x00000000, find the cursor object, referred to by rCursor, in the rOpenQueueDescriptor.CursorCollection with a Handle property equal to lpRemoteReadDesc2.pRemoteReadDesc.hCursor.

  • If no cursor object is found, return STATUS_INVALID_PARAMETER.

  • If lpRemoteReadDesc2.pRemoteReadDesc.hCursor is 0x00000000, set rCursor to NULL.

  • Create a new RemoteReadEntry, referred to as rrEntry, with the following attributes:

    • OpenQueueDescriptorHandle = lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue

    • Timeout = lpRemoteReadDesc2.pRemoteReadDesc.ulTimeout

    • UserMessagePacket = lpRemoteReadDesc2.pRemoteReadDesc.lpBuffer

    • Action = lpRemoteReadDesc2.pRemoteReadDesc.ulAction

    • RequestId = lpRemoteReadDesc2.pRemoteReadDesc.dwRequestID

  • Add rrEntry to rRemoteReadEntryCollection.

  • If the ulAction member of the lpRemoteReadDesc2.pRemoteReadDesc parameter is MQ_ACTION_RECEIVE, generate a Dequeue Message Begin event ([MS-MQDMPR] section 3.1.7.1.11) with the following inputs:

    • iQueueDesc := rOpenQueueDescriptor obtained in a preceding step.

    • iTimeout := lpRemoteReadDesc2.pRemoteReadDesc.ulTimeout.

    • iTag := lpRemoteReadDesc2.pRemoteReadDesc.dwRequestID.

    • iCursor := rCursor.

  • If the ulAction member of the lpRemoteReadDesc2.pRemoteReadDesc parameter is MQ_ACTION_PEEK_CURRENT, generate a Peek Message ([MS-MQDMPR] section 3.1.7.1.15) event with the following inputs:

    • iQueueDesc := rOpenQueueDescriptor obtained in a preceding step.

    • iTimeout := lpRemoteReadDesc2.pRemoteReadDesc.ulTimeout.

    • iCursor := rCursor.

  • If the ulAction member of the lpRemoteReadDesc2.pRemoteReadDesc parameter is MQ_ACTION_PEEK_NEXT, generate a Peek Next Message ([MS-MQDMPR] section 3.1.7.1.14) event with the following inputs:

    • iQueueDesc := rOpenQueueDescriptor obtained in a preceding step.

    • iTimeout := lpRemoteReadDesc2.pRemoteReadDesc.ulTimeout.

    • iCursor := rCursor.

  • If the rStatus value returned from the preceding events is MQ_OK (0x00000000), the server MUST process the returned rMessage as follows:

    • Generate a Construct a UserMessage Packet ([MS-MQDMPR] section 3.1.7.1.30) event with the following argument:

      • iMessage := rMessage

    • Generate a Serialize Message to Buffer ([MS-MQDMPR] section 3.1.7.1.32) event with the following arguments:

      • iMessage := rMessage

      • iBuffer := rUserMessage returned by the  Construct a UserMessage Packet event.

    • Assign rUserMessage to lpRemoteReadDesc2.pRemoteReadDesc.lpBuffer.

    • Assign rUserMessage.BaseHeader.PacketSize to lpRemoteReadDesc2.pRemoteReadDesc.dwSize

    • Assign the least significant seven bytes of rMessage.LookupIdentifier to the SequentialId member of lpRemoteReadDesc2.

  • Remove the RemoteReadEntry ADM element instance from rRemoteReadEntryCollection for which RemoteReadEntry.RequestId equals lpRemoteReadDesc2.pRemoteReadDesc.dwRequestID and RemoteReadEntry.OpenQueueDescriptorHandle equals lpRemoteReadDesc2.pRemoteReadDesc.hRemoteQueue.

  • If rStatus is MQ_OK (0x00000000) and lpRemoteReadDesc2.pRemoteReadDesc.ulAction is MQ_ACTION_RECEIVE, set pphContext to rrEntry; otherwise, delete rrEntry.

  • Return rStatus.