MQInstanceToFormatName

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.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_SERVICE_NOT_AVAILABLE

Cannot connect to the Queue Manager.

MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL

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

Remarks

Format names are not stored by MSMQ; 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 MQLocateBegin or MQLocateNext locates a queue and stores its identifier, not the queue's format name, in Active Directory.

Other format name translation functions include MQPathNameToFormatName and MQHandleToFormatName.

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mq.h.
  Import Library: Use mqrt.lib.
  Unicode: Defined only as Unicode.

See Also

MQGetQueueProperties, MQGetQueueSecurity, MQHandleToFormatName, MQLocateBegin, MQLocateNext, MQOpenQueue, MQPathNameToFormatName, MQSetQueueProperties, PROPID_Q_INSTANCE