Updated: July 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);  


[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:




[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:




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


[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:


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.


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


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

The MQMoveMessage function returns an HRESULT.


Indicates success.


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


MSMQ is unable to enlist in the specified transaction.


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


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


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

System_CAPS_ICON_note.jpg 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).


Insufficient resources to complete the operation.


MSMQ service is not available/running.

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.

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 =   
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);  
return hr;  

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.


Community Additions