 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This property specifies the name of the computer where the queue's messages are stored, if the queue is public or private, and the name of the queue.
Syntax
HRESULT get_PathName( BSTR* pbstrPathName ); HRESULT put_PathName( BSTR bstrPathName ); |
Parameters
- pbstrPathNameor bstrPathName
-
Specifies the name of the computer where the queue's messages are stored. The maximum length for the complete Message Queuing pathname is MQ_MAX_Q_NAME_LEN (124 Unicode characters).
Return Value
The following table describes the common return values.
| Value | Description |
|---|---|
|
S_OK |
Success |
|
E_INVALIDARG |
One or more arguments are invalid |
|
E_NOTIMPL |
The function contains no implementation |
|
E_OUTOFMEMORY |
Out of memory |
Remarks
The MSMQQueueInfo.PathNameproperty is the only property required when calling the MSMQQueueInfo.Createmethod.
When setting this property, you can specify the UNC or DNS pathname for the queue.
The MSMQQueueInfo.PathNameproperty cannot be reset after the queue is created. An MQ_ERROR_PROPERTY_NOTALLOWED error is returned if an attempt is made to set this property after the queue is created.
Pathname Syntax
Here are three examples of Message Queuing pathnames. The first two examples indicate two public queues, one on a local computer and the other on a remote computer, and the third example indicates a private queue.
 Copy Code
|
|
|---|---|
"myMachine\myPublicQueue" "otherMachine\otherPublicQueue" "myMachine\Private$\myPrivateQueue" |
|
As a shortcut, you can substitute a period "." for the local machine, so myPublicQueue and myPrivateQueue could be specified on the local machine as follows.
|
Copy Code
|
|
|---|---|
".\myPublicQueue" ".\Private$\myPrivateQueue" |
|
Valid Characters and Maximum Size
The set of valid characters for the queue pathname vary depending on the version of Message Queuing that is creating the queue.
The following table lists the characters that cannot be used.
| Message Queuing version | Invalid queue name characters |
|---|---|
|
MSMQ 1.0 |
\ (back slash) ; semicolons) CR (ascii 13); private queues only LF (ascii 10); private queues only |
|
MSMQ 2.0 and later |
\ (back slash) ; (semicolons) CR (ascii 13) LF (ascii 10) + (plus) , (comma) " (double quote) |
The name of the queue is not case sensitive (for example, "MyQueue" and "myQueue" are treated as the same name) and can be up to 124 Unicode characters.
The maximum length of the name of the queue is 124 Unicode characters. However, using names longer than 64 Unicode characters can cause a slight reduction in performance. Further, they are not easily displayed in the directory service.
Public and Private Queues
Public queues are available to other applications and are registered in the directory service.
Private queues are not available to other applications and are registered on the local computer. They are only created on the local computer. The application is responsible to ensure that all queue names on the local computer are unique.
If a private queue name exists when MSMQQueueInfo.Createis called, Message Queuing returns an MQ_ERROR_QUEUE_EXISTS error to the application.
Foreign Queues
Foreign public queues (queues located outside the enterprise) are created in the same way as a Message Queuing public queue. For foreign queues, the PathNameproperty specifies the name of the foreign computer as it is defined in the directory service.
Referencing queues within a
cluster
To access a queue within a cluster, use the virtual server or node in place of the name of the computer. Message Queuing runs on the node independently from virtual servers that are running on the node.
Null characters in strings
Message Queuing COM components ignore characters that follow the first Null character in a string without returning an error.
Setting and Retrieving the Queue
Pathname
To specify the pathname when creating the queue, set the MSMQQueueInfo.PathNameproperty and call the MSMQQueueInfo.Createmethod.
To retrieve the stored pathname of a queue, call the MSMQQueueInfo.Refreshmethod and inspect the MSMQQueueInfo.PathNameproperty.
Equivalent Function
property
When using functions, the pathname of the queue can be set and retrieved using the PROPID_Q_PATHNAME property.
Requirements
| Header | mqoai.h |
| Library | mqoa.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |