MSMQQueue.Receive

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 Receive method of the MSMQQueue object retrieves the first message in the queue, removing the message from the queue when the message is read.

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

Parameters

Transaction

[in, optional] 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 you do not need to retrieve the message body, 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 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 IMSMQMessage interface).

Error Codes

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

Remarks

Receive retrieves (reads and deletes) the first message in the queue. It does not use the cursor created when the queue is opened, and should not be called when navigating the queue using the cursor.

If no message is found, execution of the Receive method is blocked until a message arrives 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 Receive call to block execution until a message arrives.

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

If the connection between the local computer (the RPC client) and the remote computer (the RPC server) breaks during a call to the Receive 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 Receive 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.

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.

To retrieve a message within a transaction, set the Transaction argument to an MSMQTransaction object or to one of the constants listed in the description of this argument, or use its default setting (the default setting of Transaction is MQ_MTS_TRANSACTION). If you need to guarantee that no transaction will be used (for example, if you are retrieving a message from a non-transactional queue within a transactional COM+ or MTS component), set Transaction to MQ_NO_TRANSACTION.

Messages cannot be retrieved from remote queues within a transaction.

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.

To retrieve messages, the queue must be 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.

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.

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.

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

Equivalent API Function

When using API function calls, use MQReceiveMessage to retrieve messages in the queue. To retrieve messages using this function, set the dwAction parameter to the appropriate value.

For information on	See
Message Queuing transaction support, including types of transactions	Transactions

Example Code

The following examples are included in Using Message Queuing.

For an example of	See
Reading messages in the specified queue synchronously	C/C++ COM Code Example: Reading Messages Asynchronously Visual Basic Code Example: Reading Messages Asynchronously
Using event notification to read messages in a queue asynchronously	C/C++ COM Code Example: Reading Messages Asynchronously Visual Basic Code Example: Reading Messages Asynchronously

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.