Cursor Behavior when Retrieving Messages
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 messages are retrieved from the queue, Message Queuing moves the cursor to the next message (or to the end of the queue) for the receiving application. Thus, Message Queuing automatically moves the cursor to the next location in the queue for the subsequent peek-current or receive-current operation. (This does not apply to other cursors that may be pointing to the same message).
Note
Do not perform a peek-next operation immediately after a message is removed from the queue. Message Queuing has already moved the cursor for you. If you do, Message Queuing will return an error indicating you are trying to skip a message. Always perform a peek-current operation or another receive-current operation after removing a message from the queue.
Calls to Retrieve Messages
The following illustration shows the function and COM method calls used to retrieve a message from the queue and look at the next message. Note that this example starts with the cursor already pointing to Message A. If the receiving application wants to remove the message it makes a receive-current call to remove the message. Then the following peek-current call moves the cursor to Message B.
.jpeg "<No Change>")
Reaching the End of the Queue
When the last message in a queue is retrieved, Message Queuing moves the cursor to the end of the queue when the next peek or receive current operation is called, and then waits for a new message or a time-out to occur.
When a new message arrives the cursor is always moved to the new messages, regardless of where the message is placed in the queue. Typically messages are inserted at the end of the queue, however, messages can be placed anywhere within the queue depending on their priority level.
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 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 |
| Example code that navigates a queue based on cursors. | Navigating Queue Examples |