MQGetQueueProperties

The MQGetQueueProperties function retrieves the specified set of 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. The queue must be specified using a public or private format name. You cannot specify a queue using a direct format name.

pQueueProps

[in, out] Pointer to the MQQUEUEPROPS structure where the properties are specified.

On input, the cProp 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 indicates their status (to use the property status array, include aStatus in MQQUEUEPROPS declaration).

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

Cannot access Active Directory.

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

The properties of a public queue can be retrieved at any time; however, you can only retrieve the properties of a private queue if it is 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 pathname (PROPID_Q_PATHNAME) or label (PROPID_Q_LABEL), the corresponding property's variant type must be initially set to VT_NULL so that MSMQ knows to allocate memory for the returned value. After using the retrieved value, the application must then call MQFreeMemory to free the memory allocated by MSMQ.

To retrieve the queue's identifier (PROPID_Q_INSTANCE) or type (PROPID_Q_TYPE), a buffer of type CLSID must be declared to hold the returned GUID.

A public queue's properties cannot be retrieved if there is no connection to Active Directory. This restriction applies to dependent client computers, independent client computers (working offline), and MSMQ routing servers (FRS).

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

MQFreeMemory, PROPID_Q_LABEL, PROPID_Q_PATHNAME