PROPID_Q_PATHNAME

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

(Required to create the queue.) The PROPID_Q_PATHNAME property specifies the queue path name of the queue. The path name includes the name of the computer where messages belonging to the queue are stored, an indication of whether the queue is public or private, and the name of the queue.

Property ID

PROPID_Q_PATHNAME

Type Indicator

VT_LPWSTR

MQPROPVARIANT Field

pwszVal

Property Value

String containing the Message Queuing path name.

Remarks

The PROPID_Q_PATHNAME property is the only property required when creating a queue. To specify the path name of the queue, specify PROPID_Q_PATHNAME in the MQQUEUEPROPS structure and call MQCreateQueue. When setting this property you can specify the UNC or DNS path name for the queue.

An MQ_ERROR_PROPERTY_NOTALLOWED error is returned if any attempt is made to set this property after the queue is created.

The path name of a queue includes the name of the computer where the messages for the queue are stored, an optional PRIVATE$ keyword indicating that the queue is private, followed by the name of the queue.

The name of the queue is case insensitive (for example, "MyQueue" and "myQueue" are treated as the same name).

When specifying the name of the computer in the path name, use its NetBIOS or full DNS name. The maximum length allowed for the computer name in the address specification is 256 Unicode characters. Also, queue names longer than 124 Unicode characters are not supported. Using names longer than 64 Unicode characters for public queue names may cause a slight reduction in performance. Furthermore, they are not easily displayed in the directory service.

Here are three examples of Message Queuing path names. 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.

"myComputer\myPublicQueue"  
"otherComputer\otherPublicQueue"  
"myComputer\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 responsibility of the application to ensure that all queue names on the local computer are unique. If a queue name already exists when MQCreateQueue is called, Message Queuing returns an MQ_ERROR_QUEUE_EXISTS error to the application.

To retrieve the path name of a queue stored in the directory service, 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 Message Queuing to allocate the memory needed for the path name retrieved. After you no longer need the path name buffer, you must free the memory allocated for it using MQFreeMemory.

To create a foreign queue, specify the name of the foreign computer as it is defined in the directory service.

The set of valid characters for the queue path name varies, depending on the version of Message Queuing that is creating the queue. The following table lists the characters that cannot be used.

Equivalent COM Property

When using COM components, the path name of the queue can be set and retrieved using the MSMQQueueInfo.PathName property.

Example Code

The following code fragments show how PROPID_Q_PATHNAME is specified in arrays that can be used to initialize an MQQUEUEPROPS structure for setting and retrieving the path name of the queue.

To Set the Path Name of a Queue

LPWSTR wszPathName = L".\\TestQueue";  
aQueuePropID[i] = PROPID_Q_PATHNAME;            // Property identifier  
aQueuePropVar[i].vt = VT_LPWSTR;                // Type indicator  
aQueuePropVar[i].pwszVal = wszPathName;         // Path name of the queue  

To Retrieve the Path Name of a Queue

aQueuePropID[i] = PROPID_Q_PATHNAME;            // Property identifier  
aQueuePropVar[i].vt = VT_NULL;                   // Type indicator  
i++;  

The following examples are included in Using Message Queuing.

See Also

Queue Properties
MQCreateQueue
MQFreeMemory
MQGetQueueProperties
MQLocateBegin
MQQUEUEPROPS