MQHandleToFormatName

A version of this page is also available for

Windows Embedded CE 6.0 R3

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 lpwcsFormatName buffer (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 lpwcsFormatName buffer is too small to contain the format name string.

• MQ_ERROR_INVALID_HANDLE
  The queue handle specified in hQueue is 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 MQHandleToFormatName is called.

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

The other format name translation function supported is MQPathNameToFormatName.

Requirements

See Also

Reference

MQGetQueueProperties
MQPathNameToFormatName
MQSetQueueProperties