MQInstanceToFormatName

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 MQInstanceToFormatName function returns a format name for the queue based on the identifier provided.

This function does not check to see if the identifier is valid.

HRESULT APIENTRY MQInstanceToFormatName(  
  GUID * pGUID,               
  LPWSTR lpwcsFormatName,    
  LPDWORD lpdwCount          
);

Parameters

pGUID

[in] Pointer to the queue identifier (a GUID structure).

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

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

Remarks

Format names are not stored by Message Queuing; the format name is created when MQInstanceToFormatName is called.

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 identifier (PROPID_Q_INSTANCE). Typically, this happens when MQLocateNext locates a queue and stores its identifier, not the queue's format name, in the directory service.

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

Other format name translation functions include MQPathNameToFormatName and MQHandleToFormatName.

Example Code

The following code example is included in Using Message Queuing.

For an example of	See
Opening a queue when only the queue's identifier (GUID) is known	C/C++ Code Example: Opening a Queue Using a Queue Identifier

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.