MQMoveMessage

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 MQMoveMessage function moves messages between a queue and its subqueue, or between two subqueues within the same main queue.

HRESULT MQMoveMessage(  
  QUEUEHANDLE sourceQueue,   
  QUEUEHANDLE targetQueue,   
  ULONGLONG lookupID,   
  ITransaction* pTransaction);

Parameters

sourceQueue

[in] A handle of the queue that the message has to be moved from. The source queue must be opened with MQ_RECEIVE_ACCESS, and with either of the following share modes:

MQ_DENY_NONE

MQ_DENY_RECEIVE_SHARE

targetQueue

[in] A handle of the subqueue to which the message is to be moved. The target subqueue must be opened with MQ_MOVE_ACCESS (which requires the user to have peek permission for the queue) and with either of the following share modes:

MQ_DENY_NONE

MQ_DENY_RECEIVE_SHARE

lookupID

[in] The identity of the message that needs to be moved.

pTransaction

[in] A pointer to an ITransaction interface, a constant, or NULL. The value NULL indicates the message is not moved as part of a transaction. The constant values that can be used for this parameter are:

MQ_MTS_TRANSACTION

Ensures that the Message Queuing service (MSMQ) verifies that the application is running in the context of a COM+ transaction. If MSMQ determines that the application is running within the context of a COM+ (Component Services) transaction, the message is moved within the current COM+ transaction. Otherwise, the message is moved outside of a transaction.

MQ_SINGLE_MESSAGE

Specifies that the message is moved in a single-message transaction.

MQ_XA_TRANSACTION

Specifies that the call is part of an externally coordinated, XA-compliant transaction.

Return Value

The MQMoveMessage function returns an HRESULT.

MQ_OK

Indicates success.

MQ_ERROR_ACCESS_DENIED

The source queue or the target queue was not opened with the proper access mode.

MQ_ERROR_TRANSACTION_ENLIST

MSMQ is unable to enlist in the specified transaction.

MQ_ERROR_TRANSACTION_USAGE

The MQMoveMessage function is invoked as a part of a transaction, but the source or the target queue is not a transactional queue.

MQ_ERROR_DTC_CONNECT

MSMQ is unable to connect to the Microsoft Distributed Transaction Coordinator (DTC).

MQ_ERROR_STALE_HANDLE

Either the source or target queue handles were obtained in a previous session of the MSMQ Queue Manager service.

Note

Calling MQMoveMessage with a stale source or target queue handle fails with MQ_ERROR_STALE_HANDLE if the queue is local. If the queue is remote, the call fails with 0x80070006 (invalid handle).

MQ_ERROR_INSUFFICIENT_RESOURCES

Insufficient resources to complete the operation.

MQ_ERROR_SERVICE_NOT_AVAILABLE

MSMQ service is not available/running.

Remarks

If the pTransaction parameter is set to a value other than NULL, the message will be moved from the source queue to the target queue as part of a transaction. The transaction object can be obtained internally from Message Queuing (by calling MQBeginTransaction) or externally from the MS DTC.

Example

The following sample code shows how to move a message from a main queue to a subqueue.

HANDLE sourceQueue = NULL;  
HANDLE targetQueue = NULL;  
LCWSTR wszOrdersQueue =   
               "DIRECT=OS:mymachine\private$\orders;";  
LCWSTR wszRejectedOrdersQueue =   
       "DIRECT=OS: mymachine \private$\orders;rejectedorders";  
// Open the source queue.  
hr = MQOpenQueue(wszOrdersQueue, MQ_RECEIVE_ACCESS,   
                             MQ_DENY_RECEIVE_SHARE, &sourceQueue);  
if (FAILED(hr))  
{  
    return hr;  
}  
// Open the target queue.  
hr = MQOpenQueue(wszRejectedOrdersQueue, MQ_MOVE_ACCESS,   
                                       MQ_DENY_RECEIVE_SHARE, &targetQueue);  
if (FAILED(hr))  
{  
    return hr;  
}  
// Move the message.  
hr = MQMoveMessage(sourceQueue, messageLooukpID, targetQueue, NULL);  
MQCloseQueue(sourceQueue);  
MQCloseQueue(targetQueue);  
return hr;

Requirements

Windows NT/2000/XP/Vista: Requires Windows Vista or later.

Windows 95/98/Me: Not supported.

Header: Declared in Mqoai.h.

Library: Use Mqoa.lib.

Share via