MQGetQueueProperties

The MQGetQueueProperties function retrieves the specified properties for a specific queue.

HRESULT APIENTRY MQGetQueueProperties(
  LPCWSTR lpwcsFormatName,  
  MQQUEUEPROPS *pQueueProps  
);
 

Parameters

lpwcsFormatName

[in] Pointer to the format name string of the queue whose properties will be retrieved. Use a public or private format name to specify the queue. You cannot specify a queue using a direct format name.

pQueueProps

[in, out] Pointer to the MQQUEUEPROPS structure that specifies which properties to retrieve.

On input, the cProps member of MQQUEUEPROPS specifies the number of properties to be retrieved, and the aPropID array specifies the specific properties.

On output, the aPropVar array indicates the current values of the requested properties, and the optional aStatus array, if it was included in MQQUEUPROPS, indicates the status of the properties.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_ACCESS_DENIED

The process does not have the correct access rights to get the queue's properties. For a complete list of queue access rights, see Access Control.

To change access rights, call MQSetQueueSecurity.

MQ_ERROR_ILLEGAL_FORMATNAME

The lpwcsFormatName parameter specified an illegal format name.

MQ_ERROR_ILLEGAL_PROPERTY_VT

The variant type of a property does not match the expected variant type. For example, for PROPID_Q_TYPE, the expected variant types are VT_NULL or VT_CLSID. For PROPID_Q_PATHNAME and PROPID_Q_LABEL, the expected variant type is VT_NULL.

MQ_ERROR_NO_DS

No connection with the Site Controller server. Cannot access the MQIS.

MQ_ERROR_PROPERTY

One or more properties resulted in an error.

MQ_ERROR_SERVICE_NOT_AVAILABLE

Cannot connect to the Queue Manager.

MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION

The lpwcsFormatName parameter specified a direct format name. You cannot get properties from a queue by accessing it directly.

MQ_INFORMATION_DUPLICATE_PROPERTY

The same property appears more than once in the aPropID array, this information is returned on the second appearance of the property.

MQ_INFORMATION_PROPERTY

One or more of the properties resulted in a warning code even though the function was completed.

MQ_INFORMATION_UNSUPPORTED_PROPERTY

Not a valid property identifier. The property is ignored.

Remarks

All queue properties can be retrieved; however, you can only retrieve the properties of private queues if they are located on your local computer.

If the format name of the queue is unknown, see Format Name to find ways to obtain a new format name.

To retrieve the queue's MSMQ pathname or label, the corresponding property's variant type (PROPID_Q_PATHNAME or PROPID_Q_LABEL) must be initially set to VT_NULL. If it is not set to VT_NULL, the operation fails and MQ_ERROR_ILLEGAL_PROPERTY_VT is returned.

If a property value specified by pQueueProps is set to VT_NULL, MSMQ allocates the memory needed to store the returned value when MQGetQueueProperties is called. When this happens, the application must free the memory allocated for the returned property value by calling MQFreeMemory.

For a complete discussion on retrieving a queue's properties, see Retrieving a Queue's Properties Using API Functions.

A public queue's properties cannot be retrieved by independent client computers running offline. For information on offline operations, see MSMQ Offline Support.

See Also

MQFreeMemory, PROPID_Q_LABEL, PROPID_Q_PATHNAME

© 1997 by Microsoft Corporation. All rights reserved.