MQCreateCursor (Windows CE 5.0)
This function creates a cursor for a queue and returns a handle to the cursor. This cursor is used to maintain a specific location in a queue when reading the queue's messages.
HRESULT APIENTRY MQCreateCursor(QUEUEHANDLE hQueue,PHANDLE phCursor);
Parameters
- hQueue
[in] Handle to the queue you want to create a cursor for. - phCursor
[out] Pointer to a variable that receives the resulting cursor handle.
Return Values
- MQ_OK
Indicates success. - MQ_ERROR_INVALID_HANDLE
The queue handle specified in hQueue is not valid. - MQ_ERROR_STALE_HANDLE
The specified queue handle was obtained in a previous session of the Queue Manager service. To obtain a fresh handle, close the queue and open it again.
Remarks
Use the MQCreateCursor function with MQReceiveMessage to read messages that are not at the front of the queue. (This includes reading messages synchronously or asynchronously.)
You do not need to create a cursor to read the first message in a queue.
When reading messages within a transaction, MSMQ does not roll back cursor movement if the transaction is aborted.
For example, if you have a queue with two messages, A1 and A2, and you remove message A1 while in a transaction, MSMQ moves the cursor to the next message, A2. However, if the transaction is aborted, message A1 is inserted into the queue but the cursor remains pointing at message A2.
To close the cursor, call MQCloseCursor.
Requirements
OS Versions: Windows CE 2.0 and later. Versions prior to 2.12 require the MSMQ add-on pack.
Header: Mq.h.
Link Library: Msmqrt.lib.
See Also
MQCloseCursor | MQReceiveMessage
Send Feedback on this topic to the authors