MQReceiveMessage

The MQReceiveMessage function allows you to read messages in the queue. When reading messages, you can either peek at (not removing them) or retrieve the messages (removing them) in the queue.

Messages can be read either synchronously, asynchronously, or through a transaction.

HRESULT APIENTRY MQReceiveMessage(
  QUEUEHANDLE hSource,                   
  DWORD dwTimeout,                       
  DWORD dwAction,                        
  MQMSGPROPS pMessageProps,              
  LPOVERLAPPED lpOverlapped,             
  PMQRECEIVECALLBACK fnReceiveCallback,  
  HANDLE hCursor,                        
  Transaction *pTransaction              
);

Parameters

hSource

[in] Handle to the queue that contains the message. For transactions, specify a queue on a local computer.

dwTimeout

[in] Time, in milliseconds, to wait for the message. Can be set to INFINITE.

dwAction

[in] How the message is read in the queue. Specify one of the following:

MQ_ACTION_RECEIVE: Reads the message at the current cursor location and removes it from the queue.
MQ_ACTION_PEEK_CURRENT: Reads the message at the current cursor location but does not remove it from the queue. The cursor remains pointing at the current message.
If a cursor was not created by MQCreateCursor (hCursor is NULL), the queue's cursor can only point to the first message in the queue.
MQ_ACTION_PEEK_NEXT: Reads the next message in the queue (skipping the message at the current cursor location) but does not remove it from the queue.
MQCreateCursor must be called (hCursor is not NULL) before MQ_ACTION_PEEK_NEXT can be used.

pMessageProps

[in, out] On input, a pointer to an MQMSGPROPS structure that specifies which message properties will be received. Can be set to NULL.

On output, it contains the received message property values.

lpOverlapped

[in, out] Pointer to an Overlapped structure. Set to NULL for synchronous receive and transactions.

fnReceiveCallback

[in] Pointer to the callback function. Set to NULL for synchronous receive and transactions. For information on using a callback function, see the callback example in Reading Messages Asynchronously.

hCursor

[in] Handle to cursor for looking at messages in the queue. Can be set to NULL. See the following Remarks section.

pTransaction

[in] Must be a pointer to a transaction object, a constant, or NULL.

Transaction object can be obtained internally from MSMQ (by calling MQBeginTransaction), or externally from Microsoft® DTC (Distributed Transaction Coordinator).

Constants include:

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

NULL indicates the message is not retrieved as part of a transaction.

Return Values

MQ_OK: Indicates success.
MQ_ERROR_ACCESS_DENIED: The action specified in dwAction does not agree with the access rights the queue was opened with.
MQ_ERROR_BUFFER_OVERFLOW: The supplied buffer for the message body is too small. The part of the message body that fits into the buffer is copied, but the message is not removed from the queue.
MQ_ERROR_SENDERID_BUFFER_TOO_SMALL: The supplied sender identification buffer is too small to hold the sender identification.
MQ_ERROR_SYMM_KEY_BUFFER_TOO_SMALL: The supplied symmetric key buffer is too small to hold the symmetric key.
MQ_ERROR_SENDER_CERT_BUFFER_TOO_SMALL: The supplied sender certificate buffer is too small to hold the security certificate.
MQ_ERROR_SIGNATURE_BUFFER_TOO_SMALL: The supplied signature buffer is too small to hold the message's digital signature.
MQ_ERROR_PROV_NAME_BUFFER_TOO_SMALL: The supplied provider name buffer is too small to hold the cryptographic service provider's name.
MQ_ERROR_LABEL_BUFFER_TOO_SMALL: The supplied message label buffer is too small to hold the message's label.
MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL: The supplied format name buffer is too small to hold the format name of the queue.
MQ_ERROR_DTC_CONNECT: MSMQ was unable to connect to the MS DTC.
MQ_ERROR_INSUFFICIENT_PROPERTIES: One of the following message properties was specified (in pMessageProps) without its associated length property: PROPID_M_ADMIN_QUEUE, PROPID_M_DEST_QUEUE, PROPID_M_LABEL, PROPID_M_RESP_QUEUE, PROPID_M_XACT_STATUS_QUEUE, or PROPID_M_PROV_NAME.
MQ_ERROR_INVALID_HANDLE: The queue handle specified in hSource is not valid.
MQ_ERROR_IO_TIMEOUT: No message was received within the time-out period specified by dwTimeout.
MQ_ERROR_MESSAGE_ALREADY_RECEIVED: A message that is currently pointed at by the cursor has been removed from the queue. It can be removed by another process or by another call to MQReceiveMessage using a different cursor, or the message time-to-be-received timer has expired.
MQ_ERROR_OPERATION_CANCELLED: The operation was canceled before it could be completed. For example, the queue handle was closed by another thread while waiting for a message.
MQ_ERROR_PROPERTY: One or more message properties specified in pMessageProps resulted in an error.
MQ_ERROR_QUEUE_DELETED: The queue was deleted before the message could be read. The specified queue handle is no longer valid and the queue handle must be closed.
MQ_ERROR_ILLEGAL_CURSOR_ACTION: MQ_ACTION_PEEK_NEXT cannot be used with the current cursor position.
MQ_ERROR_SERVICE_NOT_AVAILABLE: Cannot connect to the Queue Manager.
MQ_ERROR_STALE_HANDLE: The specified queue handle was obtained in a previous session of the Queue Manager service. Close the queue and open it again to obtain a fresh handle.
MQ_ERROR_TRANSACTION_USAGE: Transaction error. An attempt was made to open a remote queue for read access from within a transaction, or an attempt was made to read a message from a non-transaction queue from within a transaction.
MQ_INFORMATION_PROPERTY: One or more of the properties specified in pMessageProps resulted in a warning code even though the function is completed.

Remarks

All message properties can be read. However, only those properties specified in the pMessageProps parameter are returned to the calling application; other properties are simply discarded when the message is read. For example, when browsing for messages, some applications may choose to retrieve the size of the message without retrieving the message body itself. To do this, PROPID_M_BODY_SIZE is included in pMessageProps and PROPID_M_BODY is not; the size of the message is returned to the calling application and the message body is not.

The hCursor parameter contains the handle to a cursor created by MQCreateCursor. Using a cursor is optional and is only needed when you want to read messages that are not at the front of the queue.

When using a cursor, you must peek at the first message in the queue by setting dwAction to MQ_ACTION_PEEK_CURRENT followed by subsequent calls with dwAction set to MQ_ACTION_PEEK_NEXT.

The dwAction parameter specifies how MSMQ reads the message (either peek or receive) and which message is read. For a description of how MSMQ reads the messages in the queue, see:

To retrieve the message body, PROPID_M_BODY must be specified in pMessageProps. The VT field of the corresponding element in the aPropVar array should be set to VT_UI1 | VT_VECTOR, allowing MSMQ to use the buffer specified in CAUI1 to store the message. If the supplied buffer is too small to contain the entire message body, MQReceiveMessage fails and MQ_ERROR_BUFFER_OVERFLOW is returned. The buffer is filled to capacity, and the full message remains in the queue. When this happens, the other properties specified by pMessageProps are still read.

To retrieve the size of the message, specify PROPID_M_BODY_SIZE in pMessageProps. MSMQ sets PROPID_M_BODY_SIZE to the size of the message body, even if MQReceiveMessage fails because the message body exceeded the buffer allocated by PROPID_M_BODY. When retrieving the message body size, the CAUI1 structure associated with the PROPID_M_BODY property does not indicate the size. The cElems field of the CAUI1 structure merely indicates the maximum message body, which could be copied into the pElems buffer. The cElems field is never modified by MSMQ.

Not all properties require the application to specify the property type in the VT field of the aPropVar array. For these properties, the corresponding VT field in the aPropVar array can be set to VT_NULL.

When reading messages in a queue, the function's time-out timer (dwTimeout) can be set to 0, a specific amount of time, or INFINITE. A message can be retrieved if it is available at that period of time.

Synchronously Reading Messages

To synchronously read messages, fnReceiveCallback and lpOverlapped must be set to NULL. When this is done, the calling thread is blocked until a suitable message is available or a time-out occurs.

For an example of using MQReceiveMessage to read messages synchronously, see Reading Messages Synchronously.

Asynchronously Reading Messages

When asynchronously reading messages, MQReceiveMessage returns a SUCCESS value as soon as a suitable message is found. Otherwise, the function returns immediately with the return value MQ_INFORMATION_OPERATION_PENDING. This return value indicates that the operation is pending and will be completed as soon as a suitable message can be found. Asynchronous receive is based on standard Microsoft® Win32® mechanisms.

There are three possible ways to read messages asynchronously:

By using a callback function (fnReceiveCallback is not NULL). In this case, the message is not retrieved by MQReceiveMessage. It is retrieved by the registered callback function. Once registered, a callback function cannot be unregistered.
When multiple asynchronous MQReceiveMessage calls are outstanding, several callbacks are registered; upon arrival of a message, the first registered callback is called.
By using a Windows Event mechanism (fnReceiveCallback is NULL and lpOverlapped is not NULL). In this case, the hEvent member of the specified OVERLAPPED structure contains a valid handle to an event object. When a suitable message arrives, or a time-out occurs, the event object is set to the signaled state.
For more information on the OVERLAPPED structure, see the Microsoft Platform SDK.
By using a Windows NT completion port mechanism (fnReceiveCallback is NULL and lpOverlapped is not NULL). A queue handle can be associated with a completion port to receive messages asynchronously.
For more information, see CreateIOCompletionPort in the Microsoft Platform SDK.

The output parameters to an asynchronous call to MQReceiveMessage should be kept intact until the operation completes (that is, you cannot free them or reuse them). Use automatic variables with caution.

For an example of using MQReceiveMessage to read messages asynchronously, see Reading Messages Asynchronously.

Reading Message in Transactions

If MQReceiveMessage is called as part of a transaction (pTransaction is not set to MQ_NO_TRANSACTION or NULL), the following parameters must be set accordingly:

The lpOverlapped and fnReceiveCallback parameters must be set to NULL. The operation must be synchronous receive.
The hSource parameter must specify a queue on a local computer.

When the call is made, MSMQ performs the following tasks.

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 sender's administration queue. The class property of the acknowledgment message is MQMSG_CLASS_ACK_RECEIVE. For information on lTransaction::Commit, see the Platform SDK.

For more information about MSMQ transactions, see MSMQ Transactions.

Messages in Administration Queues

When reading acknowledgment messages in an administration queue, you can see if the original message failed by looking at the class property (PROPID_M_CLASS) of the acknowledgment message. The class property will contain a positive or negative acknowledgment.

If the class property is positive, the original message body is not included in the acknowledgment message. If the class property is negative, the message body is included as the message body of the acknowledgment message. For a complete description of all the properties of the acknowledgment message, see Acknowledgment Messages.

Responding to Messages

The receiving application can pass PROPID_M_RESP_QUEUE to MQReceiveMessage to see if the sending application expects a response to the message. The messages sent back to the response queue specified by this property must be understood by the original sending application.

When receiving a message, always check PROPID_M_RESP_QUEUE to see if it is not NULL. If it is not NULL, send responses to the specified response queue.

Response queue handles returned by MQOpenQueue can be cached to eliminate the need to call MQOpenQueue several times for the same response queue.

For an example of sending response messages, see Sending Messages that Request a Response.

Examples

For examples of using MQReceiveMessage, see Reading Messages Using a Cursor.

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mq.h.
  Import Library: Use mqrt.lib.
  Unicode: Defined only as Unicode.