Required (to create the queue). The PROPID_Q_PATHNAME property specifies the MSMQ pathname of the queue. The MSMQ pathname includes the name of the computer where the queue's message's are stored, whether the queue is public or private, and the name of the queue.
The PROPID_Q_PATHNAME property is the only property required when you are creating a queue. To specify the queue's MSMQ pathname when you are creating the queue, specify PROPID_Q_PATHNAME in the MQQUEUEPROPS structure and call MQCreateQueue.
An MQ_ERROR_PROPERTY_NOTALLOWED error is returned if any attempt is made to set this property after the queue is created.
For public queues, PROPID_Q_PATHNAME includes the name of the computer where the queue's messages are stored followed by the name of the queue. For private queues, add PRIVATE$\ between the name of the local computer and the queue name (private queues can only be created on the local computer).
Here are three examples of MSMQ pathnames. The first two examples indicate two public queues (one on a local computer and the other on a remote computer). The third example indicates a private queue.
"myMachine\myPublicQueue"
"otherMachine\otherPublicQueue"
"myMachine\Private$\myPrivateQueue"
As a shortcut, you can substitute a period "." for the local computer. So myPublicQueue and myPrivateQueue could be specified on the local computer as:
".\myPublicQueue"
".\Private$\myPrivateQueue"
Private queues are only created on the local computer. It is the application's responsibility to ensure that all queue names on the local computer are unique. If a queue name already exists when MQCreateQueue is called, MSMQ returns an MQ_ERROR_QUEUE_EXISTS error to the application.
To retrieve the MSMQ pathname of a queue, specify PROPID_Q_PATHNAME in the MQQUEUEPROPS structure, and then call MQGetQueueProperties (or MQLocateBegin when starting a query) and examine its returned value.
When specifying PROPID_Q_PATHNAME in the MQQUEUEPROPS structure, set its type indicator to VT_NULL. This tells MSMQ to allocate the memory needed for the pathname. Later, this allocated memory must be freed using MQFreeMemory.
To create a foreign queue, specify the name of the foreign machine as it is defined in Active Directory. (For information on defining foreign machines, see "To create a foreign computer" in the Administrator's Guide.)
This example shows how PROPID_Q_PATHNAME is specified in the MQQUEUEPROPS structure for both setting and retrieving the queue's pathname. Note that when retrieving the queue's pathname, the type indicator is set to VT_NULL.
//To set the queue's pathname
aPropID[i] = PROPID_Q_PATHNAME; // Property identifier
aVariant[i].vt = VT_LPWSTR; // Type indicator
aVariant[i].pwszVal = L".\\MyPublicQueue"; // Pathname of queue
//To retrieve the queue's pathname
aPropID[i] = PROPID_Q_PATHNAME; // Property identifier
aVariant[i].vt = VT_NULL; // Type indicator
i++
| For complete examples of… | See… |
|---|---|
| Creating a public or private queue | Creating a Queue |
| Retrieving the pathname of the queue | Retrieving PROPID_Q_PATHNAME |
Windows NT: Requires version 4.0 SP3 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in mq.h.
Import Library: Use mqrt.lib.
Unicode: Defined only as Unicode.
MQCreateQueue, MQGetQueueProperties, MQLocateBegin