MSMQQueue.PeekNextByLookupId

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

(Introduced in MSMQ 3.0.) The PeekNextByLookupId method of the MSMQQueue object returns the message that follows the message referenced by the lookup identifier supplied, but does not remove the message from the queue.

Function PeekNextByLookupId( _  
  ByVal LookupId As Variant, _  
  [ ByRef WantDestinationQueue As Variant ], _  
  [ ByRef WantBody As Variant ], _  
  [ ByRef WantConnectorType As Variant ] _  
  ) As MSMQMessage

Parameters

LookupId

[in] Lookup identifier of the message referenced (in C++, a VARIANT containing a ULONGLONG that specifies the lookup identifier).

Note

The message returned follows the message referenced.

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.

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 IMSMQMessage3 interface).

Error Codes

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

Remarks

PeekNextByLookupId is part of a set of methods that can be used to locate messages and navigate the queue without using cursors. For information on all the methods included in this set, see Navigating with Lookup Identifiers.

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 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.

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.

In C++ COM applications, you must use a smart pointer to the IMSMQQueue3 interface to expose the PeekNextByLookupId method.

Equivalent API Function

When using API function calls, use MQReceiveMessageByLookupId to peek at messages based on their lookup identifier. To peek at messages using this function, set the dwLookupAction parameter to the appropriate value.

Example Code

The following example is included in Using Message Queuing.

For an example of	See
Using lookup identifiers to navigate through the messages in a queue	Visual Basic Code Example: Navigating Using Lookup Identifiers.

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows Server 2003.

Windows 95/98/Me: Unsupported.

Header: Declared in Mqoai.h.

Library: Use Mqoa.lib.

Share via