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

No connection with the Site Controller server. Cannot access the MQIS.

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 you need a format name to specify a queue when calling MQOpenQueue, MQGetQueueProperties, MQSetQueueProperties, MQGetQueueSecurity, or MQSetQueueSecurity and the only available information is the queue's MSMQ pathname.

The format name of a public queue cannot be returned by an independent client computer running offline. 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.

See Also

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

© 1997 by Microsoft Corporation. All rights reserved.