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