MQSetQueueProperties

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 MQSetQueueProperties function sets the properties of a specific queue.

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

Parameters

lpwcsFormatName

[in] Pointer to the format name string of the queue whose properties will be set. A public or private format name can be used to specify the queue. You can only use a direct format name to set the properties of a local private queue.

pQueueProps

[in] Pointer to the MQQUEUEPROPS structure that specifies the properties to be set.

On input, the cProp member of MQQUEUEPROPS specifies the number of properties to be set, the aPropID array specifies their property identifiers, and the aPropVar array indicates the new values of the specified properties.

On output, the optional aStatus array, if it was included in MQQUEUEPROPS, indicates the status of the properties.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_ACCESS_DENIED (0xC00E0025)

The access rights for setting the properties of the queue are not allowed for the calling process. For a complete list of queue access rights, see Access Control.

To change the access rights of the queue, call MQSetQueueSecurity.

MQ_ERROR_ILLEGAL_FORMATNAME (0xC00E001E)

The lpwcsFormatName parameter specified an illegal format name.

MQ_ERROR_ILLEGAL_PROPERTY_VALUE (0xC00E0018)

An illegal property value is specified.

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

One of the IN parameters supplied by the operation is not valid.

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 by the lpwcsFormatName parameter cannot be used. You cannot reference a public queue or a remote private queue in a call to this function using a direct format name, nor can you set the queue properties of a journal, dead-letter, or connector queue.

MQ_ERROR_WRITE_NOT_ALLOWED (0xC00E0065)

The properties for the queue cannot be set in the MSMQ Information Store (MQIS) because a new MQIS server is being installed.

MQ_INFORMATION_PROPERTY (0x400E0001)

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

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 following queue properties cannot be set by MQSetQueueProperties.

Property Name	Reason
PROPID_Q_BASEPRIORITY	For public queues only. Cannot be set for private queues.
PROPID_Q_CREATE_TIME	Set by Message Queuing.
PROPID_Q_INSTANCE	Set by Message Queuing.
PROPID_Q_MODIFY_TIME	Set by Message Queuing.
PROPID_Q_PATHNAME	Can only be set when the queue is created.
PROPID_Q_TRANSACTION	Can only be set when the queue is created.

When setting the properties of a public queue, some clients may still see the old settings registered in the directory service after the properties have been changed. Changes to the directory service (such as setting properties) are replicated from domain controller to domain controller, which can cause delays in the availability of new information. Consequently, clients using a specific domain controller may still see the old property settings, even though the settings of the properties were changed by MQSetQueueProperties. Replication delays, including communication network delays such as down links, are controlled by the Message Queuing administrator.

A public queue's properties cannot be set if there is no connection to the directory service. This restriction applies to dependent client computers, independent client computers that are working offline, and Message Queuing routing servers (FRS).

Equivalent COM Method

When using COM components, you can set the properties of a queue by setting the properties of an MSMQQueueInfo object that has been initialized to represent the queue and then calling the Update method of the same object.

For information on	See
A complete list of queue properties	Message Queuing Properties
Obtaining a format name for opening a 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
Setting the authentication level	C/C++ Code Example: Setting PROPID_Q_AUTHENTICATE
Setting the base priority level	C/C++ Code Example: Setting PROPID_Q_BASEPRIORITY
Setting the journaling level and the maximum size of the queue journal	C/C++ Code Example: Setting PROPID_Q_JOURNAL C/C++ Code Example: Setting PROPID_Q_JOURNAL_QUOTA
Setting the queue label	C/C++ Code Example: Setting PROPID_Q_LABEL
Setting the multicast address associated with the queue	C/C++ Code Example: Setting PROPID_Q_MULTICAST_ADDRESS
Setting the privacy level of the queue	C/C++ Code Example: Setting PROPID_Q_PRIV_LEVEL
Setting the maximum size of the queue	C/C++ Code Example: Setting PROPID_Q_QUOTA
Setting the queue type	C/C++ Code Example: Setting 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.