Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function returns a direct format name for the queue based on its handle.

Syntax 

HRESULT APIENTRY MQHandleToFormatName(
  QUEUEHANDLE 
hQueue,
  LPWSTR 
lpwcsFormatName,
  LPDWORD 
lpdwCount
);

Parameters

hQueue

[in] Handle to the queue.

lpwcsFormatName

[out] Buffer to receive the format name for the queue.

lpdwCount

[in, out] On input, specifies the length of the lpwcsFormatNamebuffer (in Unicode characters).

Private queues require at least 54 characters.

A NULL pointer is not allowed.

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 Value

MQ_OK

Indicates success.

MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL

The lpwcsFormatNamebuffer is too small to contain the format name string.

MQ_ERROR_INVALID_HANDLE

The queue handle specified in hQueueis not valid.

MQ_ERROR_SERVICE_NOT_AVAILABLE

Cannot connect to the Queue Manager.

MQ_ERROR_STALE_HANDLE

The specified queue handle was obtained in a previous session of the Queue Manager service. To obtain a fresh handle, close the queue and open it again.

Remarks

Format names are not stored by MSMQ; the format name is created when MQHandleToFormatNameis called.

Typically, this function is used when you need a format name to specify a queue when calling MQGetQueuePropertiesor MQSetQueueProperties.

The other format name translation function supported is MQPathNameToFormatName.

Note:
OS versions prior to 2.12 require the MSMQ add-on pack.

Requirements

Header mq.h
Library msmqrt.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later
Note Versions prior to 2.12 require the MSMQ add-on pack

See Also