MQCreateCursor

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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.

Syntax

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 Value

• 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

See Also

Reference

MQCloseCursor
MQReceiveMessage