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:
-
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.
-
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.
-
Moves the cursor to the next message location and peeks at the message.
-
Moves the cursor to the start of the queue.
-
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.
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 |