MQHandleToFormatName

Article
10/19/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The MQHandleToFormatName function returns a format name for the queue or subqueue based on its handle.

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

Parameters

hQueue

[in] Handle to the queue or subqueue.

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). Public queues require at least 44 Unicode characters; private queues require at least 54. 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, but the output value can be used to allocate a sufficiently large buffer for a repeated function call.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL (0xC00E001F)

The lpwcsFormatName buffer is too small to contain the format name string.

MQ_ERROR_INVALID_HANDLE (0xC00E0007)

The queue handle specified in hQueue is not valid.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

MQ_ERROR_STALE_HANDLE (0xC00E0056)

The specified queue handle was obtained in a previous session of the queue manager service. Close the queue and open it again to obtain a fresh handle.

Remarks

Format names are not stored by Message Queuing; 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, MQSetQueueProperties, MQGetQueueSecurity, or MQSetQueueSecurity.

This function can be called while operating offline. Message Queuing does not use information stored in the directory service to generate a format name from the queue handle. For information about offline operations, see Message Queuing Offline Support.

Other format name translation functions include MQPathNameToFormatName and MQInstanceToFormatName.

Example

The following example code shows how to retrieve the format name of a subqueue from the handle of a subqueue.

LPWSTR wszRejectedOrdersQueue;

hr = MQHandleToFormatName(hQueue, wszRejectedOrdersQueue, 255,);

if (FAILED(hr))

{

return hr;

}

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.