MSMQQueue.Peek (Windows CE 5.0)
This method looks 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.
HRESULT Peek( VARIANT* WantDestinationQueue,VARIANT* WantBody,VARIANT* ReceiveTimeout,MSMQMessage** ppmsg);
Parameters
WantDestinationQueue
Optional (default is FALSE). If TRUE, MSMQMessage.DestinationQueueInfo is 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.ppmsg
First message in the queue.
Return Values
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.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.
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.Peek call to block execution until a message arrives.
WantDestinationQueue and WantBody parameters
The WantDestinationQueue and WantBody parameters can be used 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 MQSendMessage is called, the message body is treated as an array of bytes.
- If the body type was set to an invalid body type before MQSendMessage is called, the message can be retrieved, but an error occurs when you try to read the message body.
Peeking at Messages Asynchronously
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.
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.ResponseQueueInfo property 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 the 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 MQReceiveMessage to peek at messages in the queue.
To peek at messages using this function, set the dwAction parameter to the appropriate value.
Requirements
OS Versions: Windows CE .NET 4.0 and later.
Header: Mqoai.h.
Link Library: Mqoa.lib.
See Also
MSMQMessage | MSMQMessage.DestinationQueueInfo | MSMQMessage.ResponseQueueInfo | MSMQMessage.ResponseQueueInfo | MSMQMessage.Send | MSMQQueue | MSMQQueueInfo | MSMQQueue.PeekCurrent | MSMQQueue.PeekNext | MSMQQueue.ReceiveCurrent
Send Feedback on this topic to the authors