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 );
[in] Pointer to the queue identifier (a GUID structure).
[out] Pointer to a buffer to receive the format name for the queue.
[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.
The buffer pointed to by lpwcsFormatName is too small to contain the format name string.
The Message Queuing service is not available.
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.
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
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.