MQReceiveMessageByLookupId

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 MQReceiveMessageByLookupId function reads a specific message in the queue or subqueue. Messages can be referenced by a lookup identifier or by their position at the front or end of the queue.

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

HRESULT APIENTRY MQReceiveMessageByLookupId(  
  QUEUEHANDLE hSource,                     
  ULONGLONG ullLookupId,                    
  DWORD dwLookupAction,                    
  MQMSGPROPS * pMessageProps,               
  LPOVERLAPPED lpOverlapped,               
  PMQRECEIVECALLBACK fnReceiveCallback,    
  ITransaction * pTransaction                
);

Parameters

hSource

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

ullLookupId

[in] The lookup identifier of a message or 0 ("0" is used when accessing the first or last message in the queue).

dwLookupAction

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

MQ_LOOKUP_PEEK_FIRST

Peeks at the first message in the queue but does not remove it from the queue. The ullLookupId parameter must be set to 0.

MQ_LOOKUP_PEEK_PREV

Peeks at the message preceding the message specified by ullLookupId but does not remove it from the queue.

MQ_LOOKUP_PEEK_CURRENT

Peeks at the message specified by ullLookupId but does not remove it from the queue.

MQ_LOOKUP_PEEK_NEXT

Peeks at the message following the message specified by ullLookupId but does not remove it from the queue.

MQ_LOOKUP_PEEK_LAST

Peeks at the last message in the queue but does not remove it from the queue. The ullLookupId parameter must be set to 0.

MQ_LOOKUP_RECEIVE_FIRST

Retrieves the first message in the queue and removes it from the queue. The ullLookupId parameter must be set to 0.

MQ_LOOKUP_RECEIVE_PREV

Retrieves the message preceding the message specified by ullLookupId and removes it from the queue.

MQ_LOOKUP_RECEIVE_CURRENT

Retrieves the message specified by ullLookupId and removes it from the queue.

MQ_LOOKUP_RECEIVE_NEXT

Retrieves the message following the message specified by ullLookupId and removes it from the queue.

MQ_LOOKUP_RECEIVE_LAST

Retrieves the last message in the queue and removes it from the queue. The ullLookupId parameter must be set to 0.

pMessageProps

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

On output, pMessageProps contains the retrieved message property values.

lpOverlapped

[in, out] A pointer to an OVERLAPPED structure that can be used in asynchronous receive operations based on a completion port or an event mechanism. Setting this parameter to a valid pointer makes the receive operation asynchronous. Set to NULL for synchronous receive operations and transactions as well as for asynchronous receive operations that do not employ an OVERLAPPED structure.

fnReceiveCallback

[in] A pointer to the callback function. Set to NULL for synchronous receive operations and transactions as well as for asynchronous receive operations that do not employ a callback function.

pTransaction

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

Transaction objects can be obtained internally from Message Queuing (by calling MQBeginTransaction), or externally from Microsoft® Distributed Transaction Coordinator (MS DTC).

Constants include:

MQ_NO_TRANSACTION

Specifies that the call is not part of a transaction.

MQ_MTS_TRANSACTION

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_SINGLE_MESSAGE

Requests a single-message transaction. Note that a request to retrieve a message in a single-message transaction using this constant is equivalent to a request to retrieve a single message from a transactional queue outside of a transaction using MQ_NO_TRANSACTION.

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 (0xC00E0025)

The access rights of the queue for performing the action specified in dwLookupAction are not allowed for the user that opened the queue.

MQ_ERROR_BUFFER_OVERFLOW (0xC00E001A)

The buffer supplied for PROPID_M_BODY, PROPID_M_COMPOUND_MESSAGE, PROPID_M_EXTENSION, or PROPID_M_SOAP_ENVELOPE is too small. Details can be retrieved from the aStatus array. In each case, the portion of the property that fits is copied to the buffer, but the message is not removed from the queue.

MQ_ERROR_DTC_CONNECT (0xC00E004C)

Message Queuing was unable to connect to the MS DTC.

MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL (0xC00E001F)

The supplied format name buffer is too small to hold the format name of the queue.

MQ_ERROR_LABEL_BUFFER_TOO_SMALL (0xC00E005E)

The supplied message label buffer is too small to hold the message's label.

MQ_ERROR_INSUFFICIENT_PROPERTIES (0xC00E003F)

A property was specified in pMessageProps without its associated length property.

MQ_ERROR_INVALID_HANDLE (0xC00E0007)

The queue handle specified in hSource is not valid.

MQ_ERROR_OPERATION_CANCELLED (0xC00E0008)

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_OPERATION_NOT_SUPPORTED_BY_REMOTE_COMPUTER (0xC00E008B)

Receiving or peeking at a message using a lookup identifier from a remote queue residing on a computer running MSMQ 1.0 or MSMQ 2.0 is not supported.

MQ_ERROR_PROPERTY (0xC00E0002)

One or more message properties specified in pMessageProps resulted in an error.

MQ_ERROR_PROV_NAME_BUFFER_TOO_SMALL (0xC00E0063)

The supplied provider name buffer is too small to hold the cryptographic service provider's name.

MQ_ERROR_QUEUE_DELETED (0xC00E005A)

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_MESSAGE_NOT_FOUND (0xC00E0088)

The message referenced by the lookup identifier does not exist. Either the lookup identifier is incorrect or the message has been removed from the queue.

MQ_ERROR_SENDER_CERT_BUFFER_TOO_SMALL (0xC00E002B)

The supplied sender certificate buffer is too small to hold the user certificate.

MQ_ERROR_SENDERID_BUFFER_TOO_SMALL (0xC00E0022)

The sender identifier buffer supplied is too small.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

MQ_ERROR_SIGNATURE_BUFFER_TOO_SMALL (0xC00E0062)

The signature buffer supplied is too small to hold the message's digital signature.

MQ_ERROR_STALE_HANDLE (0xC00E0056)

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_SYMM_KEY_BUFFER_TOO_SMALL (0xC00E0061)

The supplied symmetric key buffer is too small to hold the symmetric key.

MQ_ERROR_TRANSACTION_USAGE (0xC00E0050)

One of the following actions was attempted within the context of a transaction.

An attempt was made to read a message from a remote queue.

An attempt was made to peek a message inside a transaction.

An attempt was made to read a message from a nontransactional queue.

An attempt was made to read a message using a callback or overlap function.

MQ_INFORMATION_PROPERTY (0x400E0001)

One or more of the properties specified in pMessageProps resulted in a warning code even though the function is completed.

Remarks

The MQReceiveMessageByLookupId function is used by the receiving application to peek at or retrieve the messages in the queue. This function can be used to go directly to any message in the queue, and then navigate to the preceding or following messages.

The lookup identifier of a message (PROPID_M_LOOKUPID) is generated by Message Queuing when the message is placed in the queue (this is not the message identifier generated when the message is sent). Lookup identifiers are assigned to all messages that are put in application-generated destination, administration, and report queues, as well as system-generated journal, dead-letter, connector, and outgoing queues. The lookup identifier is unique to the queue and has no meaning outside the queue.

When retrieving messages using MQReceiveMessageByLookupId, there is no receive time-out functionality as provided in MQReceiveMessage. The message must exist when MQReceiveMessageByLookupId is called. If the message does not exist, an MQ_ERROR_MESSAGE_NOT_FOUND error is returned and the call fails.

To peek at or retrieve messages from a local outgoing queue, the corresponding remote destination queue must be opened with administrative access in addition to peek or receive access. Specifically, the handle to the queue (hSource) must be obtained by calling MQOpenQueue with the dwAccess parameter set to MQ_PEEK_ACCESS | MQ_ADMIN_ACCESS or MQ_RECEIVE_ACCESS | MQ_ADMIN_ACCESS. Local administrative permissions are also needed to retrieve messages from an outgoing queue.

Messages cannot be read from a queue that resides on a remote computer without a direct connection. Opening a queue with receive access or peek access requires a direct connection to the computer where the queue resides, and an RPC session is established during calls to receive or peek at messages. For more information, see Opening Remote Queues with Peek or Receive Access.

Equivalent COM Method

When using COM components, you can receive messages referenced by a lookup identifier or by their position at the front or end of the queue by calling the MSMQQueue.ReceiveByLookupId, MSMQQueue.ReceiveFirstByLookupId, MSMQQueue.ReceiveLastByLookupId, MSMQQueue.ReceiveNextByLookupId, and MSMQQueue.ReceivePreviousByLookupId methods of the MSMQQueue object. You can peek at messages referenced by a lookup identifier or by their position at the front or end of the queue by calling the MSMQQueue.PeekByLookupId, MSMQQueue.PeekFirstByLookupId, MSMQQueue.PeekLastByLookupId, MSMQQueue.PeekNextByLookupId, and MSMQQueue.PeekPreviousByLookupId methods of the MSMQQueue object.

Example Code

The following code examples are included in Using Message Queuing.

For an example of	See
Peeking at a message with a given lookup identifier	C/C++ Code Example: Reading Messages By Lookup Identifier
Navigating through a queue using the lookup identifiers of the messages	C/C++ Code Example: Navigating Using Lookup Identifiers

The following code shows how to receive or peek at a message from a subqueue using a lookup ID.

PCWSTR wszRejectedOrdersQueue =   
                 ”Direct=OS:mymachine\private$\orders;rejectedorders”;  
hr = MQReceiveMessageByLookupID(hQueue, LookupID,  
                           MQ_LOOKUP_PEEK_CURRENT, &msgprops,   
                                    NULL, NULL, MQ_NO_TRANSACTION);

Requirements

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

Windows 95/98/Me: Unsupported.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.