MQPathNameToFormatName

Article
10/19/2016

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

The MQPathNameToFormatName function returns a format name based on the path name provided.

HRESULT APIENTRY MQPathNameToFormatName(  
  LPCWSTR lpwcsPathName,    
  LPWSTR lpwcsFormatName,    
  LPDWORD lpdwCount         
);

Parameters

lpwcsPathName

[in] UNC or DNS path name of the queue. Either private or public Message Queuing path names are valid.

lpwcsFormatName

[out] Pointer to a buffer to receive the format name for the queue.

lpdwCount

[in, out] On input, specifies the length of the lpwcsFormatName buffer (in Unicode characters). When Message Queuing is in domain mode, public queues require at least 44 Unicode characters; private queues require at least 54. When Message Queuing is in workgroup mode, the number of Unicode characters required by a direct format name for a private queue depends on the queue name.

On output, indicates the length of the returned format name string, including the null-terminating character. If the output value is greater than the initial input value, the supplied buffer is not large enough to contain the complete format name string and MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL is returned. In this case, only a portion of the format name is returned, but the output value can be used to allocate a sufficiently large buffer for a repeated function call.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL (0xC00E001F)

The buffer pointed to by lpwcsFormatName is too small to contain the format name string.

MQ_ERROR_ILLEGAL_QUEUE_PATHNAME (0xC00E0014)

The lpwcsPathName parameter contains an illegal Message Queuing path name string.

MQ_ERROR_NO_DS (0xC00E0013)

A connection with the directory service cannot be established. Verify permissions for accessing the directory service.

MQ_ERROR_QUEUE_NOT_FOUND (0xC00E0003)

(Public queues only) The queue is not registered in the directory service.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

Note

Apart from generic Message Queuing error codes, this function may return ADSI and LDAP error codes. For example, LDAP_BUSY (0x8007200E) is returned when the directory service server is busy.

Remarks

Private (local only) and public Message Queuing path names can be specified.

Typically, this function is used when the only available information is the queue's Message Queuing path name and you need the format name for calls to MQOpenQueue, MQGetQueueProperties, MQSetQueueProperties, MQGetQueueSecurity, or MQSetQueueSecurity.

Message Queuing uses information stored in the directory service to generate a public format name from the path name of a local or remote public queue. The format name of a public queue cannot be retrieved if there is no connection to the directory service.

This function can be called by a computer that is a member of a domain or a workgroup to obtain the format name of a local private queue, but cannot be called by a domain computer operating offline to obtain the format name of a public queue. When the computer is operating in domain mode, the function returns the private format name for a local private queue, and when the computer is operating in workgroup mode, the function returns its direct format name. For information on offline operations, see Message Queuing Offline Support.

Other format name translation functions include MQInstanceToFormatName and MQHandleToFormatName.

To generate a DNS path name for the queue, use MQGetQueueProperties to retrieve the PROPID_Q_PATHNAME_DNS property of the queue.

Example Code

The following code examples are included in Using Message Queuing.

For an example of	See
Generating a format name from a queue path name	C/C++ Code Example: Opening a Queue

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.