Cursors and COM Components

 

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

When the receiving application calls the COM components provided by Message Queuing, a cursor is automatically created each time a queue is opened to retrieve messages. Once the queue is opened, the following methods can be called to peek at and retrieve the messages in the queue:

• MSMQQueue.PeekCurrent

  Peeks at the message at the current cursor position. When the receiving application peeks at the message, it must call MSMQQueue.PeekNext to move the cursor to the next message.

  This method is also used to move the cursor to the first message location before messages can be retrieved.

• MSMQQueue.ReceiveCurrent

  Retrieves the message at the current cursor position, removing it from the queue. When a message is removed from the queue Message Queuing moves the cursor to the next message location when the next MSMQQueue.PeekCurrent or MSMQQueue.ReceiveCurrent call is made.

• MSMQQueue.PeekNext

  Moves the cursor to the next message location and peeks at the message.

• MSMQQueue.Reset

  Moves the cursor to the start of the queue.

• MSMQQueue.EnableNotification

  Enables notification for asynchronous operations.

Synchronously Reading Messages

A typical mechanism for synchronously reading the messages in a queue is to call MSMQQueue.PeekCurrent to peek at the first message in the queue (when the cursor is created it does not point to the first message in the queue). Then use a loop construct to process each message in the queue. To remove the message call MSMQQueue.ReceiveCurrent followed by MSMQQueue.PeekCurrent to peek at the next message. To leave the message call MSMQQueue.PeekNext to move the cursor and peek at the next message.

Note

When MSMQQueue.ReceiveCurrent is called, Message Queuing moves the cursor to the next message when the next receive or peek operation is called. If you try to move the cursor by calling MSMQQueue.PeekNext directly after calling MSMQQueue.ReceiveCurrent, an error is returned because Message Queuing is already moving the cursor.

Asynchronously Reading Messages

When you asynchronously read the messages in the queue, calls to MSMQQueue.EnableNotification can also affect the cursor. When this method's Cursor parameter is set to MQMSG_NEXT, the cursor is moved to the next message in the queue when the Arrived event is fired.

Note

When enabling notification, use caution in making calls to MSMQQueue.Peek or MSMQQueue.Receive. These calls do not use the cursor and are always pointing to the first message in the queue.

Receive Methods That Do Not Use Cursors

The following methods should not be called by the receiving application if the application is using the cursor to navigate through the queue. The first two methods always peek at or retrieve the first message in the queue regardless of cursor position. The remaining methods use the message lookup identifier to identify a message, not the cursor.

• MSMQQueue.Peek

• MSMQQueue.Receive

• MSMQQueue.PeekByLookupId

• MSMQQueue.PeekFirstByLookupId

• MSMQQueue.PeekPreviousByLookupId

• MSMQQueue.PeekNextByLookupId

• MSMQQueue.PeekLastByLookupId

• MSMQQueue.ReceiveByLookupId

• MSMQQueue.ReceiveFirstByLookupId

• MSMQQueue.ReceivePreviousByLookupId

• MSMQQueue.ReceiveNextByLookupId

• MSMQQueue.ReceiveLastByLookupId

More Information

For information on	See
How a cursor is moved to the first message when the cursor is created.	Cursor Behavior when Creating a Cursor
How the cursor is moved when peeking at messages	Cursor Behavior when Peeking at Messages
How the cursor is moved when retrieving messages	Cursor Behavior when Retrieving Messages
How the cursor is moved when reaching the end of the queue	Cursor Behavior when Reaching the End of the Queue
How multiple cursors interact	Cursor Behavior when Using Multiple Cursors
How the cursor behaves when waiting for new messages at the end of the queue.	Cursor Behavior when Waiting for New Messages
How the cursor behaves when trying to read a message that was removed by someone else.	Cursor Behavior When Messages are Not Available
How the behaves when errors occur.	Cursor Behavior Due to Errors
How the cursor behaves when trying to read messages from a deleted queue	Cursor Behavior and Deleted Queues
How the cursor moves when the queue contains messages with different message priority levels.	Cursor Behavior and Message Priority
Summary of COM methods that use cursors for synchronous and asynchronous operations	Cursors and COM Components
How lookup Identifiers can be used to read messages in a queue	Navigating with Lookup Identifiers
Example code that navigates a queue based on cursors.	Navigating Queue Examples