MQDeleteQueue

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 MQDeleteQueue function deletes a queue from the directory service (in the case of public queues) or from the local computer (in the case of private queues).

HRESULT APIENTRY MQDeleteQueue(  
  LPCWSTR lpwcsFormatName    
);  

Parameters

lpwcsFormatName

[in] Pointer to the format name string of the queue to be deleted.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_ACCESS_DENIED (0xC00E0025)

The access rights for deleting this queue are not allowed for the calling process. To change access rights of the queue, call MQSetQueueSecurity.

MQ_ERROR_ILLEGAL_FORMATNAME (0xC00E001E)

The specified format name in lpwcsFormatName is illegal.

MQ_ERROR_NO_DS (0xC00E0013)

A connection with the directory service cannot be established. Verify permissions for accessing the directory service.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION (0xC00E0020)

The format name specified by lpwcsFormatName cannot be used to delete a queue. You cannot reference a public queue or a remote private queue in a call to this function using a direct format name, nor can you delete a journal, dead-letter, or connector queue.

MQ_ERROR_WRITE_NOT_ALLOWED (0xC00E0065)

The queue cannot be deleted from the MSMQ Information Store (MQIS) because a new MQIS server is being installed.

Remarks

Queues can be referenced using a public or private format name. Direct format names can be used only for local private queues. Message Queuing must be able to access the directory service to delete public queues, or the local computer to delete private queues. If the format name of the queue is unknown, see Obtaining Format Names.

Private queues registered on a remote computer, as well as journal, dead-letter, and connector queues, cannot be deleted.

Public queues cannot be deleted if there is no connection to the directory service. This restriction applies to dependent client computers, independent client computers that are working offline, and Message Queuing routing servers (FRS). (For information about offline operations, see Message Queuing Offline Support.)

When a public queue is deleted, some clients may still see the queue registered in the directory service after the queue has been deleted. A change to the directory service (such as deleting a public queue) is replicated from domain controller to domain controller, which can cause delays in the availability of new information. Consequently, clients using a specific domain controller may try to send messages to the queue, even though it has been deleted. Replication delays, including communication network delays such as down links, are controlled by the Message Queuing administrator.

If a handle to a queue is obtained by calling MQOpenQueue and then the queue is deleted before that handle is closed, any further attempts to access the queue using that handle will return MQ_ERROR_QUEUE_DELETED.

Equivalent COM Method

When using COM components, you can delete an existing public or local private queue by calling the MSMQQueueInfo.Delete method.

Deleting a Subqueue

Subqueues cannot be deleted directly using the MQDeleteQueue function. A subqueue is deleted automatically when it becomes empty and there are no open handles to the subqueue. Calling MQDeleteQueue on a subqueue will fail with the error MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION. Deleting a main queue will delete all of its subqueues and the messages within the subqueues.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.

See Also

Message Queuing Functions
MQCloseQueue
MQCreateQueue
MQOpenQueue
MQSetQueueSecurity