MSMQQueueInfo.PathName (Compact 2013)
3/26/2014
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
- pbstrPathName or 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.PathName property is the only property required when calling the MSMQQueueInfo.Create method.
When setting this property, you can specify the UNC or DNS pathname for the queue.
The MSMQQueueInfo.PathName property 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.
"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.
".\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, MSMQ 3, and MSMQ 4. |
\ (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.Create is called, Message Queuing returns an MQ_ERROR_QUEUE_EXISTS error to the application.
External Queues
External public queues (queues located outside the enterprise) are created in the same way as a Message Queuing public queue. For foreign queues, the PathName property 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.PathName property and call the MSMQQueueInfo.Create method.
To retrieve the stored pathname of a queue, call the MSMQQueueInfo.Refresh method and inspect the MSMQQueueInfo.PathName property.
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 |