Creating a Queue

All queues, both public and private, are created by calling MQCreateQueue. For a description of public and private queues, see Message Queues.

The only property required to create a queue is PROPID_Q_PATHNAME. This property tells MSMQ where to store the queue's messages, if the queue is public or private, and the name of the queue. Once the queue is created, the format name returned in the lpwcsFormatName parameter is used to open the queue. For a description of MSMQ pathnames and queue format names, see Referencing a Queue.

    To create a queue

1. Determine which computer will hold the messages for the queue. The computer's machine name is part of the queue's MSMQ pathname (PROPID_Q_PATHNAME). For private queues, the local computer must be specified.
2. Determine whether the queue should be public or private. This tells MSMQ where to register the queue: public queues are registered in Active Directory, and private queues are registered on the local machine (private queues can only be registered on the local machine). This information is part of the queue's MSMQ pathname (PROPID_Q_PATHNAME).
3. Determine the name for the queue. The queue's name is part of the queue's MSMQ pathname (PROPID_Q_PATHNAME).

   Note  The MSMQ pathname must be unique in the MSMQ enterprise. This applies to public and private queues.

4. Determine what queue properties must be set. If a queue property is not specified when calling MQCreateQueue, its default value is used. For a complete list of the queue properties that can be set when a queue is created, see the following Queue Properties section.
5. Declare the MQQUEUEPROPS structure. The index of the aVariant and aPropId arrays must match the number of queue properties specified.

   MQQUEUEPROPS QueueProps;
   PROPVARIANT aVariant[2];
   QUEUEPROPID aPropId[2];
   DWORD PropIdCount = 0;
   HRESULT hr;
   DWORD dwFormatNameBufferLength = 256;
   WCHAR szFormatNameBuffer[256];
   PSECURITY_DESCRIPTOR pSecurityDescriptor;
    

6. Fill in the MQQUEUEPROPS structure. PROPID_Q_PATHNAME is required; it indicates if the queue is public or private.

   // Set the pathname of the queue (PROPID_Q_PATHNAME).
   aPropId[PropIdCount] = PROPID_Q_PATHNAME;    // Property identifier
   aVariant[PropIdCount].vt = VT_LPWSTR;        // Type indicator
   aVariant[PropIdCount].pwszVal = L".\\MyPublicQueue";
       
   PropIdCount++;
       
   // Set the label of the queue (PROPID_Q_LABEL).
   aPropId[PropIdCount] = PROPID_Q_LABEL;    // Property identifier
   aVariant[PropIdCount].vt = VT_LPWSTR;     // Type indicator
   aVariant[PropIdCount].pwszVal = L"Test Queue";
       
   PropIdCount++;
       
       

7. Set the MQQUEUEPROPS structure.

   QueueProps.cProp = PropIdCount;           // Number of properties
   QueueProps.aPropID = aPropId;             // Ids of properties
   QueueProps.aPropVar = aVariant;           // Values of properties
   QueueProps.aStatus = NULL;                // No error reports
   pSecurityDescriptor = NULL;
       

8. Call MQCreateQueue to create the queue.

   hr = MQCreateQueue(
        pSecurityDescriptor,            // Security
        &QueueProps,                    // Queue properties
        szFormatNameBuffer,             // Output: Format Name
        &dwFormatNameBufferLength       // Output: Format Name len
        );
    
    

Examples

The following two examples show the code used to specify the MSMQ pathname and label for a public queue and and a private queue, plus a call to MQCreateQueue to create the queue.

Note  In these examples, "." is used to indicate the local machine in PROPID_Q_PATHNAME. For MSMQ servers and independent clients, the local machine is the local computer. However, for MSMQ-dependent clients, the local machine is the client's MSMQ server.

For a public queue

////////////////////////////
//  Define the MQQUEUEPROPS
//  structure.
////////////////////////////
MQQUEUEPROPS QueueProps;
PROPVARIANT aVariant[2];      // Modify for additional properties.
QUEUEPROPID aPropId[2];       // Modify for additional properties.
DWORD PropIdCount = 0;
HRESULT hr;
DWORD dwFormatNameBufferLength = 256;
TCHAR szFormatNameBuffer[ 256];
PSECURITY_DESCRIPTOR pSecurityDescriptor;

//////////////////////////////////////////
// Specify the queue's pathname and label 
// properties. Note the pathname uses "." 
// as shorthand for the local computer.
//////////////////////////////////////////

// Set the pathname of the queue (PROPID_Q_PATHNAME).
aPropId[PropIdCount] = PROPID_Q_PATHNAME;  // Property identifier
aVariant[PropIdCount].vt = VT_LPWSTR;      // Type indicator
aVariant[PropIdCount].pwszVal = L".\\MyPublicQueue";  // Pathname

PropIdCount++;

// Set the label of the queue (PROPID_Q_LABEL).
aPropId[PropIdCount] = PROPID_Q_LABEL;     // Property identifier
aVariant[PropIdCount].vt = VT_LPWSTR;      // Type indicator
aVariant[PropIdCount].pwszVal = L"Test Queue";     // Queue label

PropIdCount++;


////////////////////////////////////////////////////////
// Add additional properties here. When adding properties, 
// increment the indexes for the aVariant and aPropId arrays
// in their respective declaration statements above.
////////////////////////////////////////////////////////


////////////////////////////////////
// Set the MQQUEUEPROPS structure.
/////////////////////////////////////
QueueProps.cProp = PropIdCount;  // Number of properties
QueueProps.aPropID = aPropId;    // Ids of properties
QueueProps.aPropVar = aVariant;  // Values of properties
QueueProps.aStatus = NULL;       // No error reports
pSecurityDescriptor = NULL;      // Set default security descriptor

////////////////////////////
//Create the queue.
////////////////////////////
hr = MQCreateQueue(
pSecurityDescriptor,               // Security
     &QueueProps,                    // Queue properties
     szFormatNameBuffer,             // Output: Format Name
     &dwFormatNameBufferLength       // Output: Format Name length
     );
 

For a private queue

MQQUEUEPROPS QueueProps;
PROPVARIANT aVariant[2];
PROPVARIANT aVariant[2];      // Modify for additional properties.
QUEUEPROPID aPropId[2];       // Modify for additional properties.
HRESULT hr;
DWORD dwFormatNameBufferLength = 256;
WCHAR szFormatNameBuffer[ 256];
PSECURITY_DESCRIPTOR pSecurityDescriptor;

//////////////////////////////////////////
// Specify the queue's pathname and label 
// properties. Note the pathname uses "." 
// as shorthand for the local computer.
//////////////////////////////////////////

// Set the pathname of the queue (PROPID_Q_PATHNAME).
aPropId[PropIdCount] = PROPID_Q_PATHNAME;   // Property identifier
aVariant[PropIdCount].vt = VT_LPWSTR;       // Type indicator
aVariant[PropIdCount].pwszVal = L".\\PRIVATE$\\MyPrivateQueue"; 

PropIdCount++;

// Set the label of the queue (PROPID_Q_LABEL).
aPropId[PropIdCount] = PROPID_Q_LABEL;     // Property identifier
aVariant[PropIdCount].vt = VT_LPWSTR;      // Type indicator
aVariant[PropIdCount].pwszVal = L"Test Queue";     // Queue label

PropIdCount++;

////////////////////////////////////////////////////////
// Add additional properties here. When adding properties, 
// increment the indexes for the aVariant and aPropId arrays
// in their respective declaration statements above.
////////////////////////////////////////////////////////


////////////////////////////////////////////////////////
// Set the MQQUEUEPROPS structure.
////////////////////////////////////////////////////////
QueueProps.cProp = PropIdCount;  // Number of properties
QueueProps.aPropID = aPropId;    // Ids of properties
QueueProps.aPropVar = aVariant;  // Values of properties
QueueProps.aStatus = NULL;       // No error reports
pSecurityDescriptor = NULL;      // Set default security descriptor


///////////////////////    
//Create the queue.
///////////////////////
hr = MQCreateQueue(
     pSecurityDescriptor,            // Security
     &QueueProps,                    // Queue properties
     szFormatNameBuffer,             // Output: Format Name
     &dwFormatNameBufferLength       // Output: Format Name len
     );
 

Queue Properties

The following optional queue properties can be set by the application when creating the queue:

PROPID_Q_AUTHENTICATE

PROPID_Q_BASEPRIORITY

PROPID_Q_JOURNAL

PROPID_Q_JOURNAL_QUOTA

PROPID_Q_LABEL

PROPID_Q_PRIV_LEVEL

PROPID_Q_QUOTA

PROPID_Q_TRANSACTION

PROPID_Q_TYPE

The following properties are set by MSMQ when it creates the queue:

PROPID_Q_CREATE_TIME

PROPID_Q_INSTANCE (for public queues)

PROPID_Q_MODIFY_TIME