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 MQIS.

Other format name translation functions include MQPathNameToFormatName and MQHandleToFormatName.

See Also

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

© 1997 by Microsoft Corporation. All rights reserved.