3.2.4.6 Receiving a Message by Using a Cursor
To receive a message by using a cursor, the following inputs are expected:
QueueHandle: Handle of the queue to be read from.
TimeOut: Set to the time-out in milliseconds.
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<31> 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 MQ_ACTION_RECEIVE.
ulTimeout set to TimeOut.
dwRequestID set to rPendingRemoteReadEntry.RequestId.
Else if none of the above conditions is 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 MQ_ACTION_RECEIVE.
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).
Advise the server that the message was received by calling the RemoteQMEndReceive method with the following parameter values:
pphContext set to the rPendingRemoteReadEntry.RemoteReadHandle.
dwAck set to 0x00000002 (RR_ACK).
Remove the rPendingRemoteReadEntry element from rPendingRemoteReadEntryCollection.