MQSetQueueProperties

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. Use a public or private format name to specify the queue. You cannot specify a queue using a direct format name.
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
The process does not have the sufficient access rights to set the properties of the queue. 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_VALUE
An illegal property value is specified.
MQ_ERROR_NO_DS
Cannot access Active Directory.
MQ_ERROR_PROPERTY
One or more properties resulted in 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 set properties for a queue that is being accessed directly.
MQ_ERROR_WRITE_NOT_ALLOWED
Cannot set the properties for a queue in Active Directory.
MQ_INFORMATION_PROPERTY
One or more of the properties resulted in a warning even though the function completed.

Remarks

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

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 MSMQ.
PROPID_Q_INSTANCE Set by MSMQ.
PROPID_Q_MODIFY_TIME Set by MSMQ.
PROPID_Q_PATHNAME Can only be set when the queue is created.
PROPID_Q_TRANSACTION Can only be set when the queue is created.

For a list of the queue properties you can set, see Setting a Queue's Properties Using API Functions.

When setting the properties of a public queue, some clients may still see the old settings registered in Active Directory after the properties have been changed. Changes to Active Directory (such as setting properties) are propagated 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. Propagation delays, including communication network delays such as down links, are controlled by the MSMQ Administrator.

A public queue's properties cannot be set if there is no connection to Active Directory. This restriction applies to dependent client computers, independent client computers that are working offline, and MSMQ routing servers (FRS), (For information on offline operations, see MSMQ Offline Support.).

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

MQGetQueueProperties, MQSetQueueSecurity, PROPID_Q_BASEPRIORITY, PROPID_Q_CREATE_TIME, PROPID_Q_INSTANCE, PROPID_Q_MODIFY_TIME, PROPID_Q_PATHNAME, PROPID_Q_TRANSACTION