MQCreateQueue

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

Parameters

pSecurityDescriptor
[in] Pointer to a SECURITY_DESCRIPTOR structure that specifies the security information associated with the queue. (For information on the SECURITY_DESCRIPTOR structure, see the Microsoft Platform SDK.) Following are the default values (NULL pointer indicates all default values are used):
Owner
The process user.
Group
The process group.
DACL
Full control for the creator of the queue. All other processes can get queue properties, get queue security, and send messages to the queue.
SACL
None.
pQueueProps
[in, out] Pointer to the MQQUEUEPROPS structure that specifies the created queue's properties.

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.

lpwcsFormatName
[out] Pointer to buffer to receive the format name for the queue (NULL pointer allowed). This buffer is called the format name buffer.
lpdwFormatNameLength
[in, out] On input, specifies the length of the lpwcsFormatName buffer (in Unicode characters). Public queues require at least 44 Unicode characters; private queues require at least 54. NULL pointer is not allowed.

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.

Return Values

MQ_OK
Indicates success.
MQ_ERROR_ACCESS_DENIED
The process does not have the rights to create a queue on this computer.
MQ_ERROR_ILLEGAL_PROPERTY_VALUE
An illegal property value is specified.
MQ_ERROR_ILLEGAL_QUEUE_PATHNAME
PROPID_Q_PATHNAME contains an illegal MSMQ pathname string.
MQ_ERROR_ILLEGAL_SECURITY_DESCRIPTOR
The passed security descriptor has an invalid structure.
MQ_ERROR_INSUFFICIENT_PROPERTIES
No MSMQ pathname was specified (PROPID_Q_PATHNAME).
MQ_ERROR_INVALID_OWNER
The specified MSMQ pathname (PROPID_Q_PATHNAME) contains the name of an unrecognized machine.
MQ_ERROR_NO_DS
Cannot access Active Directory.
MQ_ERROR_PROPERTY
One or more properties resulted in an error.
MQ_ERROR_PROPERTY_NOTALLOWED
A specified property is not valid when creating the queue.
MQ_ERROR_QUEUE_EXISTS
A queue with an identical MSMQ pathname or instance already exists.
MQ_ERROR_SERVICE_NOT_AVAILABLE
Cannot connect to the Queue Manager.
MQ_ERROR_WRITE_NOT_ALLOWED
Cannot add a queue to Active Directory.
MQ_INFORMATION_FORMATNAME_BUFFER_TOO_SMALL
The queue was created successfully, but the size of the buffer for receiving the format name of the created queue is too small.
MQ_INFORMATION_PROPERTY
The function completed, but one or more properties resulted in a warning.

Remarks

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.

Examples

For an example of using MQCreateQueue, see Creating a Queue.

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

MQCloseQueue, MQDeleteQueue, MQGetQueueProperties, MQLocateBegin, MQOpenQueue, MQSetQueueProperties, PROPID_Q_INSTANCE, PROPID_Q_JOURNAL, PROPID_Q_PATHNAME, PROPID_Q_TRANSACTION