MSMQQueueInfo.Create

Article
10/19/2016

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 Create method of the MSMQQueueInfo object creates a public or private queue based on the properties of the MSMQQueueInfo object.

Sub Create( _  
  [ ByRef IsTransactional As Variant ], _  
  [ ByRef IsWorldReadable As Variant ] _  
  )

Parameters

IsTransactional

[in, optional] Boolean. When True, it indicates that the queue is a transactional queue. All messages sent to a transactional queue or read from a transactional queue must be done as part of a transaction. The default is False.

IsWorldReadable

[in, optional] Boolean. When True, all members of the Everyone group can read the messages in the queue and its queue journal. When False, only the owner can read the messages. The default is False.

Return Values

This method has no return values.

Error Codes

For information on return codes, see Message Queuing Error and Information Codes.

Remarks

You must always specify the path name of the queue before calling Create. The MSMQQueueInfo.PathName property tells Message Queuing where to store the messages of 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 you set this property, you can specify the UNC or DNS path name for the queue.

Setting other queue properties is optional. If a queue property is not set before Create is called, its default value is used when the queue is created.

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

When Create is called by an application running on a computer operating in workgroup mode to create a public queue, an MQ_ERROR (0xC00E0001) error is generated.

Private queues can only be created on the local computer. It is the responsibility of the application to ensure that no other private queue with the same name exists on the local computer (if a queue with the same name already exists, an MQ_ERROR_QUEUE_EXISTS (0xC00E0005) error is generated when Create 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 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 IsTransactional argument to True.

Foreign public queues (queues located outside the enterprise) are created in the same way as a Message Queuing public queue. For foreign queues, the MSMQQueueInfo.PathName property specifies the name of the foreign computer as it is defined in the directory service. For information on foreign computers, see Connector Services.

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

Typically queues are not created from MSMQQueueInfo objects found in an MSMQQueueInfos object because the queues already exist. However, you can create a new queue from an MSMQQueueInfo object if you delete the existing queue. A new queue will be created based on the path name. You can use the existing path name or specify a new one.

After the queue is created, the MSMQQueueInfo object can be opened multiple times. For example, the same MSMQQueueInfo object can be used to open the queue for sending messages and for retrieving messages.

Access control can be changed by setting isWorldReadable. If this argument is not set, its default value specifies Message Queuing default security. Following are the default values for the components of a queue's security descriptor.

Component	Default Value
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.
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.
SACL	None.

For information on access control, see Access Control.

Applications that may be running offline cannot create public queues while they are offline. Applications must have access to the directory service to create a public queue. 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 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.

Equivalent Function

The MQCreateQueue function is used to create queues in function calls.

For information on	See
The different types of queues provided by Message Queuing	Queues
What information Message Queuing needs to create queues	Creating Message Queues
Optional queue properties that can be set when you create a queue	Setting Queue Behavior
Transaction support provided by Message Queuing	Transactions

Example Code

The following examples are included in Using Message Queuing.

For an example of	See
Creating a public or private queue	C/C++ COM Code Example: Creating a Queue Visual Basic Code Example: Creating a Queue VBScript Code Example: Creating a Queue
Creating a Transactional Queue	C/C++ COM Code Example: Creating a Transactional Queue Visual Basic Code Example: Creating a Transactional Queue

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 Mqoai.h.

Library: Use Mqoa.lib.