Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista
The MQGetQueueProperties function retrieves the specified set of properties for a specific queue.
HRESULT APIENTRY MQGetQueueProperties( LPCWSTR lpwcsFormatName, MQQUEUEPROPS * pQueueProps );
[in] Pointer to the format name string of the queue whose properties will be retrieved. A public or private format name can be used to specify the queue. You can only use a direct format name to obtain the properties of a local private queue. See "Remarks" for limitations on private queues.
[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).
The access rights for getting the queue's properties are not allowed for the calling process. For more information on queue access rights, see Access Control.
To change access rights of the queue, call MQSetQueueSecurity.
The lpwcsFormatName parameter specified an illegal format name.
The type indicator of a property does not match the expected type indicator. For example, for PROPID_Q_TYPE, the expected type indicator is VT_NULL or VT_CLSID. For PROPID_Q_PATHNAME and PROPID_Q_LABEL, the expected type indicator is VT_NULL.
A connection with the directory service cannot be established. Verify permissions for accessing the directory service.
One or more properties resulted in an error.
The Message Queuing service is not available.
The format name specified in the lpwcsFormatName parameter cannot be used. You cannot get the queue properties of a public queue or a remote private queue using a direct format name, nor can you set the queue properties of a journal, dead-letter, or connector queue.
The same property appears more than once in the aPropID array. This information is returned on the second appearance of the property.
One or more of the properties resulted in a warning code even though the function was completed.
An invalid property identifier was specified. The property is ignored.
Apart from generic Message Queuing error codes, this function may return ADSI and LDAP error codes. For example, LDAP_BUSY (0x8007200E) is returned when the directory service server is busy.
The properties of both local and remote public queues can be retrieved; however, you can only retrieve the properties of a private queue if it is located on your local computer.
To retrieve the queue's path name (PROPID_Q_PATHNAME) or label (PROPID_Q_LABEL), the corresponding property's variant type must be initially set to VT_NULL so that Message Queuing 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 Message Queuing.
A public queue's properties cannot be retrieved if there is no connection to the directory service. This restriction applies to dependent client computers, independent client computers (working offline), and Message Queuing routing servers (FRS).
Equivalent COM Method
When using COM components, you can retrieve the properties of a queue by calling the MSMQQueueInfo.Refresh method of an MSMQQueueInfo object that has been initialized to represent the queue and then examining the properties of the same object.
|For information on||See|
|Obtaining a format name for the queue||Obtaining Format Names|
|Offline operations||Message Queuing Offline Support|
The following code examples are included in Using Message Queuing.
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.