Creating a Sub Queue
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
A subqueue cannot be created explicitly by using MQCreateQueue. Calling MQCreateQueue and specifying the format name of a subqueue returns the error code MQ_ERROR_ILLEGAL_QUEUE_PATHNAME.
A subqueue is created implicitly the first time you call MQOpenQueue to open the subqueue. Subsequent calls to MQOpenQueue will open the subqueue. Only users who can open the main queue can create a subqueue. Subqueues can be opened using one of the following access modes:
MQ_PEEK_ACCESS
Messages can only be looked at. They cannot be removed from the queue.
MQ_RECEIVE_ACCESS
Messages can be retrieved (read and removed) from the queue, peeked at, or purged.
MQ_MOVE_ACCESS
Messages can be moved between subqueues. This access mode can be used only with a subqueue.
The following sample code shows how to open a subqueue.
HANDLE hQueue = NULL;
LPCWSTR wszRejectedOrdersQueue = "Direct=OS:mymachine\private$\orders;rejectedorders";
hr = MQOpenQueue(wszDestQueueFormatName, MQ_RECEIVE_ACCESS,
MQ_DENY_NONE, &hQueue);
if (FAILED(hr))
{
return hr;
}
Subqueues can be named with any legal queue names. The name cannot be longer than 32 Unicode characters.
Addressing a Subqueue
A subqueue can be addressed only using the Direct Format Name:
Direct = os: <hostname> . \ [private$] \ <QueueName> [; Subqueue]
Direct = tcp: <ipv4address> \ [private$] \ <QueueName> [; Subqueue]
For public queues, the path name of a subqueue has the following format:
<HostName>\<QueueName>;[Subqueue]
For private queues, the path name of a subqueue has the following format:
<HostName>\private$\<QueueName>;[Subqueue]
The following are examples of subqueue path names:
mymachine\Orders;RejectedOrders
mymachine\private$\Orders;RejectedOrders
Multicasting and Subqueues
Subqueues cannot be associated with a multicast address. Applications cannot send messages directly to subqueues, so the multicast property cannot be set for subqueues.