MQPathNameToFormatName

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

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

Parameters

lpwcsPathName
[in] Pathname of the queue. Either private or public MSMQ pathnames 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). Public queues require at least 44 Unicode characters; private queues require at least 54.

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.

Return Values

MQ_OK
Indicates success.
MQ_ERROR_ILLEGAL_QUEUE_PATHNAME
The lpwcsPathName parameter contains an illegal MSMQ pathname string.
MQ_ERROR_SERVICE_NOT_AVAILABLE
Cannot connect to the Queue Manager.
MQ_ERROR_NO_DS
Cannot access Active Directory.
MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL
The buffer pointed to by lpwcsFormatName is too small to contain the format name string.

Remarks

Private (local only) and public MSMQ pathnames can be specified.

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

The format name of a public queue cannot be retrieved if there is no connection to Active Directory. This restriction applies to dependent client computers, independent client computers that are working offline, and MSMQ routing servers (FRS). (For information on offline operations, see MSMQ Offline Support.)

Other format name translation functions include MQInstanceToFormatName and MQHandleToFormatName.

Examples

For an example of using MQPathNameToFormatName, see Sending Private Messages.

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mq.h.
  Import Library: Use mqrt.lib.
  Unicode: Defined only as Unicode.

See Also

MQGetQueueProperties, MQGetQueueSecurity, MQHandleToFormatName, MQInstanceToFormatName, MQOpenQueue, MQSetQueueProperties, MQSetQueueSecurity