MQCreateQueue

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 MQCreateQueue function creates a public or private queue based on the queue properties provided.

HRESULT APIENTRY MQCreateQueue(  
  PSECURITY_DESCRIPTOR pSecurityDescriptor,    
  MQQUEUEPROPS * pQueueProps,                   
  LPWSTR lpwcsFormatName,                      
  LPDWORD lpdwFormatNameLength                 
);  

Parameters

pSecurityDescriptor

[in] Pointer to a SECURITY_DESCRIPTOR structure that specifies the user-defined security information that will be associated with the queue. The default values are used for any components of the queue's security that are not specified in this structure. If this parameter is set to a NULL pointer, all the default values are used. Following are the default values of the components of a queue's security information:

Owner

The security identifier (SID) of the queue's creator.

Group

The security identifier (SID) of the primary group to which the queue's creator belongs.

Discretionary access control list (DACL)

Full control for the creator of the queue. All other users (processes) can get queue properties, get queue security, and send messages to the queue. In MSMQ 3.0, anonymous users can only send messages to the queue, and the Computer_Name$ account of a computer that belongs to a domain can only get the properties and security of the queue and receive or peek at messages in the queue.

System access control list (SACL)

None.

pQueueProps

[in, out] Pointer to the MQQUEUEPROPS structure that specifies the properties of the queue.

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 (a NULL pointer is allowed). This buffer is called the format name buffer. In domain mode, the buffer receives the public format name for a public queue or the private format name for a local private queue, whereas in offline or workgroup mode, the buffer can receive only the direct format name for a local private queue.

lpdwFormatNameLength

[in, out] On input, specifies the length (in Unicode characters) of the format name buffer specified in lpwcsFormatName. Public queues require at least 44 Unicode characters; private queues require at least 54. If a NULL pointer is specified in lpwcsFormatName, set lpdwFormatNameLength to 0 (zero) on input.

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 (0xC00E0025)

The access rights for creating a queue on this computer are not allowed for the calling process.

MQ_ERROR_ILLEGAL_PROPERTY_VALUE (0xC00E0018)

An illegal property value is specified.

MQ_ERROR_ILLEGAL_QUEUE_PATHNAME (0xC00E0014)

PROPID_Q_PATHNAME contains an illegal Message Queuing path name string.

MQ_ERROR_ILLEGAL_SECURITY_DESCRIPTOR (0xC00E0021)

The SECURITY_DESCRIPTOR structure passed is invalid.

MQ_ERROR_INSUFFICIENT_PROPERTIES (0xC00E003F)

No Message Queuing path name was specified (PROPID_Q_PATHNAME).

MQ_ERROR_INVALID_OWNER (0xC00E0044)

The specified path name in PROPID_Q_PATHNAME contains the name of an unrecognized machine. For example, this code is returned when you try to create a queue on a machine where Message Queuing is not installed.

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

An invalid parameter was specified. For example, lpwcsFormatName is set to a NULL pointer and lpdwFormatNameLength is not set to 0 (zero) on input set.

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_PROPERTY_NOTALLOWED (0xC00E003E)

A specified property is not valid when creating the queue.

MQ_ERROR_QUEUE_EXISTS (0xC00E0005)

A queue with an identical Message Queuing path name or instance already exists.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

MQ_ERROR_WRITE_NOT_ALLOWED (0xC00E0065)

The queue cannot be added to the MSMQ Information Store (MQIS) because a new MQIS server is being installed.

MQ_INFORMATION_FORMATNAME_BUFFER_TOO_SMALL (0x400E0009)

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 (0x400E0001)

The function completed, but one or more properties resulted in a warning.

Remarks

You must always specify the PROPID_Q_PATHNAMEE property before calling MQCreateQueue. The PROPID_Q_PATHNAME property tells Message Queuing where to store the messages sent to the queue, whether the queue is public or private, and the name of the queue. A local or remote computer can be specified for a public queue, but only the local computer can be specified for a private queue. When setting this property you can specify the UNC or DNS path name for the queue.

Setting other queue properties is optional. If a property is not specified in the pQueueProps parameter, Message Queuing uses its default value when creating the queue. After the queue is created, its properties can be changed by calling MQSetQueueProperties.

Message Queuing registers public queues in the directory service and private queues on the local computer specified. All queues exist until deleted explicitly.

Private queues can be created only on the local computer. When a private queue is created, Message Queuing stores a description of the queue in the Lqs folder on the local computer (by default, %windir%\System32\MSMQ\Storage\Lqs in MSMQ 2.0 and later, and \Program Files\MSMQ\Storage\Lqs in MSMQ 1.0). 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, Message Queuing will return an MQ_ERROR_QUEUE_EXISTS error when MQCreateQueue is called.

When a private queue is created on a computer operating in domain mode, a query is sent to the directory service to obtain information from the security descriptor of the MSMQ-Configuration object, which the local Message Queuing service uses to verify that the user has the permissions needed to create a queue.

An MSMQ 3.0 computer that belongs to a Windows® 2000 or Windows Server 2003 domain uses ADSI to create a public queue and grants anonymous users the permission to send messages to the queue. Because an MSMQ 3.0 computer that belongs to an MSMQ 1.0 enterprise cannot use ADSI to create a queue, it sends an RPC call to an MQIS server to create the queue. The queue is then created with the MSMQ 1.0 default security descriptor, which does not include ANONYMOUS.

To create a transactional queue, set the PROPID_Q_TRANSACTION property to MQ_TRANSACTIONAL. This property cannot be changed once the queue is created.

Foreign queues must be public queues. Their PROPID_Q_PATHNAME property must specify the name of the foreign computer as it is defined in the directory service. For information on connecting to foreign queues, see Connector Services.

To specify target journaling, set PROPID_Q_JOURNAL to MQ_JOURNAL. You can also set the maximum size of the queue journal by setting PROPID_Q_JOURNAL_QUOTA.

Access control for the queue is based on the information supplied in the SECURITY_DESCRIPTOR structure specified in the pSecurityDescriptor parameter. The default values are used for any components of the queue's security that are not specified in this structure. If this parameter is set to a NULL pointer, all the default values are used. For information on access control, see Access Control.

Returned format name

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.

Public queues cannot be created 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). For information on offline operations, see Message Queuing Offline Support.

When creating a public queue, some clients may not be able to see the new queue registered in the directory service even though the queue exists. Changes to the directory service (such as creating a public queue) 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 not be able to open the queue, even though it exists. Replication delays, including communication network delays such as down links, are controlled by the Message Queuing administrator.

Equivalent COM Method

When using COM components, you can create a public or private queue by calling the MSMQQueueInfo.Create method.

Example Code

The following code examples are included in Using Message Queuing.

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.

See Also

Message Queuing Functions
PROPID_Q_JOURNAL
PROPID_Q_JOURNAL_QUOTA
PROPID_Q_PATHNAME
PROPID_Q_TRANSACTION