MQPurgeQueue

  • Article

 

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 MQPurgeQueue function deletes all of the messages in a queue.

HRESULT APIENTRY MQPurgeQueue(  
  HANDLE hQueue  
);

Parameters

hQueue

[in] The handle to the queue to be purged.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_INVALID_HANDLE (0xC00E0007)

The queue handle specified in hQueue is not valid.

Remarks

Applications can purge messages from a queue opened with receive access (with the dwAccess parameter of MQOpenQueue set to MQ_RECEIVE_ACCESS).

To purge messages from a local outgoing queue, the corresponding remote destination queue is opened with administrative access in addition to receive access. Specifically, the handle to the queue (hQueue) is obtained by calling MQOpenQueue with the dwAccess parameter set to MQ_RECEIVE_ACCESS | MQ_ADMIN_ACCESS. Local administrative permissions are also needed to purge messages from an outgoing queue.

Note

Messages sent to destination queues to which they cannot be delivered (for example, because the network is unavailable) will remain in the applicable outgoing queue until their time-to-reach-queue timer expires. To reduce the need to use this function to purge messages from outgoing queues, set the time-to-reach-queue property of the messages to a short time interval.

Calling this function is much more efficient than retrieving the messages in a queue using MQReceiveMessage or MQReceiveMessageByLookupId. However, because purged messages will not be delivered (in the case of outgoing queues) or not received (in the case of destination queues), Message Queuing may also return negative acknowledgment messages or place the purged messages in the appropriate dead-letter queue.

If the PROPID_M_ACKNOWLEDGE property of a purged message is set to MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE or MQMSG_ACKNOWLEDGMENT_NACK_RECEIVE (the sending application requested acknowledgments), a negative acknowledgment message will be returned to the administration queue specified by the sending application. The PROPID_M_CLASS property of each such acknowledgment message will be set to MQMSG_CLASS_NACK_PURGED for a message purged from an outgoing queue or to MQMSG_CLASS_NACK_Q_PURGED for a message purged from a destination queue.

For information about requesting acknowledgment messages, see Acknowledgment Messages.

If the PROPID_M_JOURNAL property of a purged message is set to MQMSG_DEADLETTER (the sending application requested negative source journaling), the message will be placed in the respective local dead-letter queue with its PROPID_M_CLASS property set to MQMSG_CLASS_NACK_Q_PURGED.

Note

For transactional messages in outgoing queues, Message Queuing can process the message in one of two ways. If MSMQ 1.0 semantics are required, Message Queuing will place all purged transactional message in the local transactional dead-letter queue. If MSMQ 2.0 and later semantics are required, Message Queuing will place only those transactional messages that requested negative source journaling in the local transactional dead-letter queue.

For information about requesting negative source journaling, see Source Journaling.

When you purge recoverable messages or other messages that are stored on disk from a queue, you will not see immediate changes in the size of the memory-mapped files that store these messages on the local computer. By default, these files are cleaned up only every six hours, and only message storage files that have no messages in them are deleted. For more information about message storage files, see Storage Folder Files.

Note

The functionality of the local administration API functions introduced in MSMQ 3.0 (MQMgmtAction, MQMgmtGetInfo, and MQPurgeQueue) is also available for computers running previous versions of Message Queuing. For more information, see MSMQ Local Admin API.

Equivalent COM Method

When using COM components, you can purge the messages in a queue by calling MSMQQueue.Purge.

Purging a Subqueue

The MQPurgeQueue function can be called to delete all the messages in a subqueue. Purging a main queue will not purge the messages in its subqueues.

Example Code

The following code fragments show how to use MQPurgeQueue to purge a private destination queue on a remote computer and its corresponding outgoing queue on the local computer.

To Purge a Destination Queue

WCHAR wszFormatName[] = L"PRIVATE=ae0c5671-f190-12ce-ae10-00dd0114290f\0000000d";  
QUEUEHANDLE hQueue  
HRESULT hr  
  
hr = MQOpenQueue(  
                 wszFormatName,  
                 MQ_RECEIVE_ACCESS,  
                 MQ_DENY_NONE,  
                 &hQueue  
                );  
  
hr = MQPurgeQueue(  
                  hQueue  
                 );

To Purge the Corresponding Outgoing Queue

WCHAR wszFormatName[] = L"PRIVATE=ae0c5671-f190-12ce-ae10-00dd0114290f\0000000d";  
QUEUEHANDLE hQueue  
  
hr = MQOpenQueue(  
                 wszFormatName,  
                 MQ_RECEIVE_ACCESS | MQ_ADMIN_ACCESS,  
                 MQ_DENY_NONE,  
                 &hQueue  
                );  
  
hr = MQPurgeQueue(  
                  hQueue  
                 );

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.

See Also

Message Queuing Functions
MQReceiveMessage
MQReceiveMessageByLookupId
MSMQQueue.Purge
PROPID_M_ACKNOWLEDGE
PROPID_M_CLASS
PROPID_M_JOURNAL