PROPID_Q_PATHNAME
Required (to create the queue). This property specifies the MSMQ path name of the queue. The MSMQ path name includes the name of the computer where messages belonging to the queue are stored, whether the queue is public or private, and the name of the queue.
- Type Indicator
VT_LPWSTR - PROPVARIANT Field
pwszVal - Property Values
MSMQ 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.
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$ key word indicating if the queue is private, followed by the name of the queue.
When specifying the name of the computer, use its NetBIOS or full DNS name.
The maximum length of the name of the queue is 124 Unicode characters; however, using names longer than 64 Unicode characters may cause a slight reduction in performance.
The following example shows a MSMQ path name for a private queue.
myMachine\Private$\myPrivateQueue
As a shortcut, you can substitute a period "." for the local computer. Then, myPrivateQueue could be specified on the local computer as shown.
.\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, MSMQ returns an MQ_ERROR_QUEUE_EXISTS error to the application.
To retrieve the MSMQ path name of a queue, specify PROPID_Q_PATHNAME in the MQQUEUEPROPS structure, and then call MQGetQueueProperties 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 path name. Later, this allocated memory must be freed using MQFreeMemory.
Examples
The following examples show how PROPID_Q_PATHNAME is specified in the MQQUEUEPROPS structure for setting and retrieving the path name of the queue. Note that when retrieving the path name of the queue, the type indicator is set to VT_NULL.
To set the path name of a queue
LPWSTR wszPathName = L".\\TestQueue";
aPropID[i] = PROPID_Q_PATHNAME; // Property identifier
aVariant[i].vt = VT_LPWSTR; // Type indicator
aVariant[i].pwszVal = wszPathName; // Pathname of queue
To retrieve the path name of a queue
aPropID[i] = PROPID_Q_PATHNAME; // Property identifier
aVariant[i].vt = VT_NULL; // Type indicator
i++;
Requirements
Runs on | Versions | Defined in | Include | Link to |
---|---|---|---|---|
Windows CE OS | 2.0 and later. Versions prior to 2.12 require the MSMQ add-on pack. | Mq.h |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also
MQCreateQueue, MQFreeMemory, MQGetQueueProperties, MQQUEUEPROPS
Last updated on Tuesday, July 13, 2004
© 1992-2000 Microsoft Corporation. All rights reserved.