MSMQQueue.ReceiveCurrent

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method returns the message at the current cursor location and removes the message from the queue.

Syntax

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

Parameters

• Transaction
  Optional. The following list describes the Transaction constants:

  • MQ_NO_TRANSACTION: Specifies that the call is not part of a transaction.
  • MQ_MTS_TRANSACTION: Default. Specifies that the call is part of the current Microsoft Transaction Server (MTS) transaction.
  • MQ_XA_TRANSACTION: Specifies that the call is part of an externally coordinated, XA-compliant transaction.

• WantDestinationQueue
  Optional. The 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. The default is TRUE.

  If do not need the body of the message, 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
  Current message.

Return Value

The following table describes the common return values.

Remarks

MSMQQueue.ReceiveCurrent uses the cursor created when the queue is opened to locate the message. (Do not use this method when navigating the queue using lookup identifiers.)

This method uses the cursor created when the queue is opened, and is typically used with MSMQQueue.PeekCurrent and MSMQQueue.PeekNext.

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

Use these parameters to optimize the speed of the application.

Retrieving Messages Synchronously

For synchronous calls, execution is stopped until a message is retrieved from the queue or the message's timeout timer expires.

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

Retrieving Message in Transactions

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

• Set the Transaction parameter to an MSMQTransaction object.
• Set the Transaction parameter to a constant described in the preceding table.
• Use the Transaction parameter's default setting (MQ_MTS_TRANSACTION).

To guarantee that no transaction will be used (for example, if you retrieve a message from a nontransactional queue within a transactional 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. The class property of the acknowledgment message is MQMSG_CLASS_ACK_RECEIVE.

Transaction objects cannot be reused after you commit to or abort the transaction.

If you release the transaction object without calling Commit or Abort, the transaction is aborted.

Opening queues

To retrieve messages, the queue must be opened with receive access (Access = MQ_RECEIVE_ACCESS). Messages retrieved from a queue are also removed from the queue.

Opening a queue 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.

Responding to Messages

The receiving application can determine if the sending application expects a response 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.

Message body type

When retrieving 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. (The body type property of messages can be accessed only with Message Queuing functions.)

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

• If the body type property is not set before MQSendMessage is called, the message body is treated as an array of bytes.
• If the body type is 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.

Equivalent Function

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

Requirements