MSMQQueue.PeekNext

Article
10/19/2016

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

The PeekNext method of the MSMQQueue object returns the next message after the current cursor position or waits for a suitable message to arrive, but does not remove the message from the queue.

Function PeekNext( _  
  [ ByRef WantDestinationQueue As Variant ], _  
  [ ByRef WantBody As Variant ], _  
  [ ByRef ReceiveTimeout As Variant ], _  
  [ ByRef WantConnectorType As Variant ] _  
  ) As MSMQMessage

Parameters

WantDestinationQueue

[in, optional] Boolean (in C++, a reference to a VARIANT containing a VARIANT_BOOL). The default is False. If set to True, the MSMQMessage.DestinationQueueInfo property is updated when the message is read from the queue. Setting this argument to True may slow down the operation of the application.

WantBody

[in, optional] Boolean (in C++, a reference to a VARIANT containing a VARIANT_BOOL that specifies whether the message body is retrieved). The default is True. If the message body is not needed, set this argument to False to optimize the speed of the application.

ReceiveTimeout

[in, optional] The time (in milliseconds) that Message Queuing will wait for a message to arrive when the cursor is pointing at the end of the queue (in C++, a reference to a VARIANT containing a LONG that specifies the time). This argument can be set to INFINITE, 0, or a specific amount of time. The default setting is INFINITE.

WantConnectorType

[in, optional] Boolean (in C++, a reference to a VARIANT containing a VARIANT_BOOL). The default is False. If set to True, the MSMQMessage.ConnectorTypeGuid property is retrieved. By default, Message Queuing does not retrieve the MSMQMessage.ConnectorTypeGuid property when it peeks at a message in the queue.

Return Values

An MSMQMessage object containing the properties of the message read or an MSMQMessage object set to Nothing if no message is available (in C++, a smart pointer to the IMSMQMessage interface).

Error Codes

For information on return codes, see Message Queuing Error and Information Codes.

Remarks

PeekNext uses the cursor created when the queue is opened to select the message (this method should not be used when navigating the queue using lookup identifiers). It is typically used with MSMQQueue.PeekCurrent and MSMQQueue.ReceiveCurrent when navigating through the queue.

PeekNext moves the cursor first and then looks at the message at the new location.

The MSMQQueue.PeekCurrent method must be called to point the cursor to the first message in the queue. If PeekNext is called before PeekCurrent is not called, MQ_ERROR_ILLEGAL CURSOR_ACTION is returned.

If no message is found, execution of the PeekNext method is blocked until a message is found at the new cursor position or the time set in ReceiveTimeout elapses.

The ReceiveTimeout argument is optional. If a time-out period is specified and a time-out occurs, the message object variable is set to Nothing. However, if a time-out period is not specified, the default value of ReceiveTimeout (INFINITE) forces the PeekNext call to block execution until a message arrives.

Opening a remote queue with peek access requires a direct connection to the computer where the queue resides. You cannot peek at the messages in a queue that resides on a computer that has no direct connection to the computer where your application is running. An RPC session must be established with the remote computer during calls to peek at messages. For more information, see Opening Remote Queues with Peek or Receive Access.

If the connection between the local computer (the RPC client) and the remote computer (the RPC server) breaks during a call to the PeekNext method, the client RPC service waits two hours (by default) before failing the call. At the same time, Message Queuing on the client computer cancels the RPC session and fails the call after a time interval equal to the sum of five minutes (by default) and the time specified in the ReceiveTimeout argument. Thus, you can prevent the PeekNext method from blocking execution for two hours by setting the ReceiveTimeout parameter to a short time interval. On the RPC server, RPC waits two hours (by default) after the RPC session fails before initiating the context run-down routine to release the resources allocated on the remote computer. However, if a message arrives at the new cursor position in the remote queue during this waiting period, Message Queuing tries to return the message to the client computer through RPC. At this point, RPC detects the communication failure and initiates the run-down routine at once.

When peeking at a message, you cannot look at the type of message body included in the message. Message Queuing will determine the body type based on the message's body type property (the body type property of the messages can be accessed only with Message Queuing functions). However, if the message was sent using MQSendMessage, the following situations can occur.

If the body type property was not set before MQSendMessage was called, the message body is treated as an array of bytes.
If the body type was set to an invalid body type (for valid types, see Message Body Types) before MQSendMessage was called, the message can be retrieved, but an error will occur when you try to read the message body.

The MSMQEvent object, used to read messages asynchronously, is implemented in terms of callbacks, and is limited to 64 callbacks per process. Internally, Message Queuing uses the WaitForMultipleObjects function which is limited to 64 objects per process.

The receiving application can determine if the sending application expects a response message by retrieving the MSMQMessage.ResponseDestination (introduced in MSMQ 3.0) or MSMQMessage.ResponseQueueInfo property when reading the message. If the property is set to Nothing, the sending application is not expecting a response message. For information on requesting and returning response messages, see Response Messages.

Applications can peek at messages in queues opened with peek or receive access (see MSMQQueueInfo.Open).

To peek at messages in a local outgoing queue, the corresponding remote destination queue must be opened with administrative access in addition to peek or receive access. Specifically, the MSMQQueue object must be created by calling MSMQQueueInfo.Open with the Access argument set to MQ_PEEK_ACCESS | MQ_ADMIN_ACCESS or MQ_RECEIVE_ACCESS | MQ_ADMIN_ACCESS. Local administrative permissions are also needed to peek at messages in an outgoing queue.

Equivalent API Function

When using API function calls, use MQReceiveMessage to peek at messages in the queue. To peek at messages using this function, set the dwAction parameter to the appropriate value.

Example Code

The following examples are included in Using Message Queuing.

For an example of	See
Navigating through the messages in a queue using a cursor	Visual Basic Code Example: Navigating Using Cursors
Peeking at a specific property in all the messages in a queue	Visual Basic Code Example: Verifying Acknowledgment Requests Visual Basic Code Example: Validating Authentication Visual Basic Code Example: Matching Acknowledgment Messages Visual Basic Code Example: Reading Report Messages
Filtering messages in a queue according to a specific property	Visual Basic Code Example: Acknowledgment Class Filter Visual Basic Code Example: Application-Specific Filters Visual Basic Code Example: Correlation Identifier Filters Visual Basic Code Example: Time Sent Filters

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mqoai.h.

Library: Use Mqoa.lib.