MSMQQueue.Peek

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 Peek method of the MSMQQueue object returns the first message in the queue, or waits for a message to arrive if the queue is empty. It does not remove the message from the queue.

Function Peek( _  
  [ 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 (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

Peek looks at the first message in the queue. It does not use the cursor created when the queue is opened and should not be called when you are using MSMQQueue.PeekCurrent, MSMQQueue.PeekNext, or MSMQQueue.ReceiveCurrent to navigate through the queue.

If no message is found, execution of the Peek method is blocked until a suitable message is found in the queue 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 Peek 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 Peek 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 Peek 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 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.

In C++ COM applications, you must use a smart pointer to the IMSMQQueue2 or IMSMQQueue3 interface to expose the Peek method if the WantConnectorType parameter is set.

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 example is included in Using Message Queuing.

For an example of	See
Peeking at a message to determine whether a response message will be sent	Visual Basic Code Example: Returning Response Messages

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.