The MQCreateQueue function creates a queue and registers it in Active Directory (for public queues) or on the local computer (for private queues). It also attaches the specified queue properties (default values are used for all properties that are not specified) and security attributes to the queue and returns a format name that can be used to open the queue.
HRESULT APIENTRY MQCreateQueue(
PSECURITY_DESCRIPTOR pSecurityDescriptor,
MQQUEUEPROPS *pQueueProps,
LPWSTR lpwcsFormatName,
LPDWORD lpdwFormatNameLength
);
On input, the cProp member of MQQUEUEPROPS specifies the number of queue properties supplied, the aPropID array specifies their property identifiers, and the aPropVar array specifies their values.
On output, the optional aStatus array, if it was included in MQQUEUEPROPS, indicates the status of the properties.
On output, indicates the length of the returned format name string, including the null-terminating character. If the output value is greater than the initial input value, the supplied buffer is not large enough to contain the complete format name string and MQ_INFORMATION_FORMATNAME_BUFFER_TOO_SMALL is returned. In this case, the queue is created and only a portion of the format name is returned.
You must always specify the queue's MSMQ pathname (PROPID_Q_PATHNAME) before calling MQCreateQueue. The PROPID_Q_PATHNAME property tells MSMQ where to store the queue's messages, if the queue is public or private, and the name of the queue.
Public queues are registered in Active Directory, and private queues are registered on the local computer. All queues exist until explicitly deleted.
Private queues can only be created on the local computer. When a private queue is created, MSMQ stores a description of the queue in the LQS directory on the local computer (by default, \program files\msmq\storage\lqs). Applications must ensure that no other private queues with the same name exist on a local computer. If a queue with the same name already exists, MSMQ will return an MQ_ERROR_QUEUE_EXISTS error when MQCreateQueue is called.
Setting other queue properties is optional. If a property is not specified in the pQueueProps parameter, MSMQ uses its default value when creating the queue. After the queue is created, its properties can be changed by calling MQSetQueueProperties.
To use a public queue's queue journal, pass PROPID_Q_JOURNAL and PROPID_Q_JOURNAL_QUOTA to MQCreateQueue. The journal keeps a copy of all messages retrieved from the public queue. For conceptual information about queue and machine journals, see Journal Queues.
To create a transaction queue, pass PROPID_Q_TRANSACTION to MQCreateQueue. This property cannot be changed once the queue is created.
The queue's returned format name is invalid if MQCreateQueue fails for any reason, including returning the error MQ_ERROR_QUEUE_EXISTS. If the call returns MQ_INFORMATION_FORMATNAME_BUFFER_TOO_SMALL, this means that the queue was created, but the format name could not fit in the format name buffer.
After the queue is created, its properties can be retrieved using MQGetQueueProperties and reset using MQSetQueueProperties.
Access control for the queue is based on the MSMQ default security. For information on access control, see Access Control.
Foreign queues must be public queues. Their PROPID_Q_PATHNAME property must specify the name of the foreign computer as it is defined in Active Directory. For information on connecting to foreign queues, see MSMQ Connector Server.
When creating a public queue, some clients may not be able to see the new queue registered in Active Directory even though the queue exists. A change to Active Directory (such as creating a public queue) is 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 not be able to open the queue, even though it exists. Propagation delays, including communication network delays such as down links, are controlled by the MSMQ Administrator.
Public queues cannot be created 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.
For an example of using MQCreateQueue, see Creating a Queue.
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.
MQCloseQueue, MQDeleteQueue, MQGetQueueProperties, MQLocateBegin, MQOpenQueue, MQSetQueueProperties, PROPID_Q_INSTANCE, PROPID_Q_JOURNAL, PROPID_Q_PATHNAME, PROPID_Q_TRANSACTION