MSMQQueue.ReceiveFirstByLookupId

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 ReceiveFirstByLookupId method of the MSMQQueue object returns the first message in the queue and removes the message from the queue.

Function ReceiveFirstByLookupId( _  
  [ ByRef Transaction As Variant ], _  
  [ ByRef WantDestinationQueue As Variant ], _  
  [ ByRef WantBody As Variant ], _  
  [ ByRef WantConnectorType As Variant ] _  
  ) As MSMQMessage

Parameters

Transaction

[in, optional] An MSMQTransaction object or one of the following constants (in C++, a reference to a VARIANT that specifies the object or constant):

MQ_NO_TRANSACTION: Specifies that the call is not part of a transaction.

MQ_MTS_TRANSACTION: Default. Instructs Message Queuing to verify that a COM+ object is running and that the current COM+ object is participating in a transaction. If Message Queuing finds that the application is running in the context of a COM+ (Component Services) transaction, the message is retrieved within the current COM+ transaction. Otherwise, the message is retrieved outside of a transaction. For more information, see COM+ Transactions.

MQ_XA_TRANSACTION: Specifies that the call is part of an externally coordinated, XA transaction.

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 retrieves a message from the queue.

Return Values

An MSMQMessage object containing the properties of the message retrieved 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

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

To retrieve a message within a transaction, do one of the following.

Set the Transaction argument to an MSMQTransaction object.
Set the Transaction argument to one of the constants listed in the argument description.
Use the default MQ_MTS_TRANSACTION setting of the Transaction argument.

Message Queuing performs the following tasks when a transaction is specified.

In the case of a subsequent Abort, the message is returned to its original place in the queue.
In the case of a Commit, a positive acknowledgment message is sent to the administration queue of the sending application, if acknowledgment messages were requested. The class property of the acknowledgment message is MQMSG_CLASS_ACK_RECEIVE.

Transaction objects cannot be reused after you commit or abort the transaction. If you release the transaction object without calling Commit or Abort, the transaction is automatically aborted.

Messages cannot be retrieved from remote queues within a transaction.

When retrieving 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 retrieve messages from queues opened with receive access (with the Access argument of MSMQQueueInfo.Open set to MQ_RECEIVE_ACCESS). Messages retrieved from a queue are also removed from the queue.

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

Opening a remote queue with receive access requires a direct connection to the computer where the queue resides. You cannot retrieve 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 receive 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 ReceiveFirstByLookupId method.

Equivalent API Function

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

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.

Partager via