MQGetQueueProperties

Article
10/19/2016

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    
);

Parameters

lpwcsFormatName

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

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 (0xC00E0025)

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.

MQ_ERROR_ILLEGAL_FORMATNAME (0xC00E001E)

The lpwcsFormatName parameter specified an illegal format name.

MQ_ERROR_ILLEGAL_PROPERTY_VT (0xC00E0019)

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.

MQ_ERROR_NO_DS (0xC00E0013)

A connection with the directory service cannot be established. Verify permissions for accessing the directory service.

MQ_ERROR_PROPERTY (0xC00E0002)

One or more properties resulted in an error.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION (0xC00E0020)

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.

MQ_INFORMATION_DUPLICATE_PROPERTY (0x400E0005)

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 (0x400E0001)

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

MQ_INFORMATION_UNSUPPORTED_PROPERTY (0x400E0004)

An invalid property identifier was specified. The property is ignored.

Note

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.

Remarks

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.

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

Example Code

The following code examples are included in Using Message Queuing.

For an example of	See
Retrieving the authentication level	C/C++ Code Example: Retrieving PROPID_Q_AUTHENTICATE
Retrieving the base priority level	C/C++ Code Example: Retrieving PROPID_Q_BASEPRIORITY
Retrieving the date and time the queue was created	C/C++ Code Example: Retrieving PROPID_Q_CREATE_TIME
Retrieving the identifier (GUID) of the queue	C/C++ Code Example: Retrieving PROPID_Q_INSTANCE
Retrieving the journaling level and the maximum size of the queue journal	C/C++ Code Example: Retrieving PROPID_Q_JOURNAL C/C++ Code Example: Retrieving PROPID_Q_JOURNAL_QUOTA
Retrieving the queue label	C/C++ Code Example: Retrieving PROPID_Q_LABEL
Retrieving the date and time when the queue was last modified	C/C++ Code Example: Retrieving PROPID_Q_MODIFY_TIME
Retrieving the multicast address associated with the queue	C/C++ Code Example: Retrieving PROPID_Q_MULTICAST_ADDRESS
Retrieving the path name of the queue	C/C++ Code Example: Retrieving PROPID_Q_PATHNAME C/C++ Code Example: Retrieving PROPID_Q_PATHNAME_DNS
Retrieving the privacy level of the queue	C/C++ Code Example: Retrieving PROPID_Q_PRIV_LEVEL
Retrieving the maximum size of the queue	C/C++ Code Example: Retrieving PROPID_Q_QUOTA
Retrieving the transaction level of the queue	C/C++ Code Example: Retrieving PROPID_Q_TRANSACTION
Retrieving the queue type	C/C++ Code Example: Retrieving PROPID_Q_TYPE

Requirements

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.