Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method looks at the message at the current cursor position, but does not remove the message from the queue.

When PeekCurrentis called, execution is stopped until the message is read from the queue or the receive time-out timer ( ReceiveTimeout) expires.

Syntax 

HRESULT PeekCurrent( 
  VARIANT* 
WantDestinationQueue, 
  VARIANT* 
WantBody, 
  VARIANT* 
ReceiveTimeout, 
  MSMQMessage** 
ppmsg 
);

Parameters

WantDestinationQueue

Optional (default is FALSE). If TRUE, MSMQMessage.DestinationQueueInfois updated when the message is read from the queue.

Setting this property to TRUE can slow the operation of the application.

WantBody

Optional (default is TRUE). If the body of the message is not needed, set this property to FALSE to optimize the speed of the application.

ReceiveTimeout

Optional. Specifies how long (in milliseconds) Message Queuing waits for a message to arrive when the queue is empty or the cursor is pointing at the end of the queue.

ppmsg

Current message.

Return Value

The following table describes the common return values.

Value Description

S_OK

Success

E_INVALIDARG

One or more arguments are invalid

E_NOTIMPL

The function contains no implementation

E_OUTOFMEMORY

Out of memory

Remarks

MSMQQueue.PeekCurrentuses the cursor created when the queue is opened to locate the message.

Do not use this when navigating the queue using lookup identifiers.

This method is typically used with MSMQQueue.PeekNextand MSMQQueue.ReceiveCurrentwhen navigating through the queue using the cursor.

ReceiveTimeout parameter

Optional. If a timeout period is specified and a timeout occurs, a Null message object is returned to the application.

If a timeout period is not specified, the default value of ReceiveTimeout (INFINITE) forces the MSMQQueue.PeekCurrentcall to block execution until a message arrives.

WantDestinationQueue and WantBody parameters

Use the WantDestinationQueueand WantBodyparameters to optimize the speed of the application.

Message body type

When peeking at a message, you cannot look at the type of message body included in the message. Message Queuing determines the body type based on the message's body type property. (You can only access the body type property of messages with Message Queuing functions.)

If the message is sent using MQSendMessage, the following situations can occur.

  • If the body type property was not set before MQSendMessageis called, the message body is treated as an array of bytes.

  • If the body type was set to an invalid body type before MQSendMessageis called, the message can be retrieved, but an error occurs when you try to read the message body.

Peeking at Messages Asynchronously

The MSMQEventobject, used to read messages asynchronously, is implemented in terms of callbacks, and is limited to 64 callbacks per process.

Internally, Message Queuing uses the WaitForMultipleObjectsfunction, which is limited to 64 objects per process.

Responding to Messages

The receiving application can determine if the sending application expects a response to messages by retrieving the MSMQMessage.ResponseDestination(introduced in MSMQ 3.0) or MSMQMessage.ResponseQueueInfoproperty when reading the message.

If the property is set to Null, the sending application is not expecting a response message.

Opening queues

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

Opening a queue with peek access requires a direct connection to the computer where the queue resides. You cannot peek at messages in a queue that resides on a computer that has no direct connection to the computer where your application is running.

Equivalent Function

When using function calls, use MQReceiveMessageto peek at messages in the queue. To peek at messages using this function, set the dwActionparameter to the appropriate value.

Requirements

Header mqoai.h
Library mqoa.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also