3.2.4.5 Peeking a Message by Using a Cursor

  • Article

To peek a message by using a cursor, the following inputs are expected:

QueueHandle: Handle of the queue to be peeked from.

TimeOut: Set to the time-out in milliseconds.

Action: Set to MQ_ACTION_PEEK_CURRENT or MQ_ACTION_PEEK_NEXT, as described in section 3.1.4.1.

The client MUST perform the following actions to process this event:

  • Create a PendingRemoteReadEntry (section 3.2.1.1), referred to as rPendingRemoteReadEntry, and do the following:

    • Set rPendingRemoteReadEntry.OpenQueueDescriptorHandle equal to QueueHandle.

    • Set rPendingRemoteReadEntry.RequestId equal to a value that uniquely identifies this call from all other pending calls to this protocol. This value MUST NOT be equal to the RequestId of any other PendingRemoteReadEntry in rPendingRemoteReadEntryCollection.

    • Add rPendingRemoteReadEntry to rPendingRemoteReadEntryCollection.

After creating a PendingRemoteReadEntry, the client SHOULD<30> call the RemoteQmGetVersion method to determine the capabilities of the server. The client SHOULD check for the following conditions:

  • pMajor is less than 5.

  • pMajor is equal to 5, and pMinor is less than 1.

  • pMajor is equal to 5, and pMinor is less than 1, and pBuildNumber is less than 951.

    If any of the above conditions are satisfied, the client MUST:

    • Call the RemoteQMStartReceive method and MUST specify the following parameter values for the REMOTEREADDESC structure (lpRemoteReadDesc):

      • hRemoteQueue set to the phQueue out parameter of the qmcomm:R_QMOpenRemoteQueue, as specified in [MS-MQMP] section 3.1.4.2.

      • dwQueue set to the DWORD pointed to by the dwpQueue out parameter of the qmcomm:R_QMOpenRemoteQueue, as specified in [MS-MQMP] section 3.1.4.2.

      • hCursor set to the cursor handle obtained from qmcomm:R_QMCreateRemoteCursor, as specified in [MS-MQMP] section 3.1.4.4.

      • dwSize set to 0.

      • lpBuffer set to NULL.

      • ulAction set to Action.

      • ulTimeout set to TimeOut.

      • dwRequestID set to rPendingRemoteReadEntry.RequestId.

        Else if none of the above conditions are satisfied, the client MUST:

    • Call the RemoteQMStartReceive2 method and MUST specify the following parameter values for the REMOTEREADDESC2 structure (lpRemoteReadDesc2):

      • hRemoteQueue set to the phQueue out parameter of the qmcomm:R_QMOpenRemoteQueue, as specified in [MS-MQMP] section 3.1.4.2.

      • dwQueue set to the DWORD pointed to by the dwpQueue out parameter of the qmcomm:R_QMOpenRemoteQueue, as specified in [MS-MQMP] section 3.1.4.2.

      • hCursor set to the cursor handle obtained from qmcomm:R_QMCreateRemoteCursor, as specified in [MS-MQMP] section 3.1.4.4.

      • dwSize set to 0.

      • lpBuffer set to NULL.

      • ulAction set to Action.

      • ulTimeout set to TimeOut.

      • dwRequestID set to rPendingRemoteReadEntry.RequestId.

      • SequentialId set to 0.

The client MUST then perform the following actions to process this event:

  • Set rPendingRemoteReadEntry.RemoteReadHandle to the returned pphContext.

  • Reconstruct the message, as specified in [MS-MQMQ] section 2.2.18, from the returned lpBuffer element of the REMOTEREADDESC structure (lpRemoteReadDesc), which contains a UserMessage Packet ([MS-MQMQ] section 2.2.20).

  • Remove the rPendingRemoteReadEntry element from rPendingRemoteReadEntryCollection.