The MQCreateQueue function creates a queue and registers it in MQIS (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 cProps member of MQQUEUEPROPS specifies the number of queue properties supplied, the aPropID array specifies their property identifiers, and aPropVar array specifies their values.
On output, the optional aStatus array, if it was included in MQQUEUPROPS, 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 MQIS, 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 MQIS. For information on connecting to foreign queues, see MSMQ Connector Server.
When creating public queues, some clients may not be able to detect the new queue registered in the MSMQ information even though the queue was registered. Changes to MQIS (such as creating a public queue) must be propagated from site to site, which can cause delays in the availability of current information. Consequently, clients at some sites 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 by independent client computers running offline. For information on offline operations, see MSMQ Offline Support.
For an example of using MQCreateQueue, see Creating a Queue.
MQCloseQueue, MQDeleteQueue, MQGetQueueProperties, MQLocateBegin, MQOpenQueue, MQSetQueueProperties, PROPID_Q_INSTANCE, PROPID_Q_JOURNAL, PROPID_Q_PATHNAME, PROPID_Q_TRANSACTION