MSMQQueueInfo.PathName

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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.

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.

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.

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 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