MQCreateQueue

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function creates a private queue that is registered on the local computer upon the queue's creation.

In addition, all optional queue properties specified by the MQQUEUEPROPS structure (default values are used for all properties that are not specified) are attached to the queue.

MQCreateQueue returns a format name that can be used to open the queue.

Syntax

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

Parameters

• pSecurityDescriptor
  [in] Not supported; set to NULL.

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

  On input, the following occurs:

  • The cProp member of MQQUEUEPROPS specifies the number of queue properties supplied.
  • The aPropID array specifies their property identifiers.
  • 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 the buffer to receive the format name for the queue. (A NULL pointer is allowed.) This buffer is called the format name buffer.

• lpdwFormatNameLength
  [in, out] On input, specifies the length of the lpwcsFormatName buffer (in Unicode characters).

  Private queues require at least 54 characters.

  A 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 Value

• 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 path name string.

• MQ_ERROR_ILLEGAL_SECURITY_DESCRIPTOR
  The passed security descriptor has an invalid structure.

• MQ_ERROR_INSUFFICIENT_PROPERTIES
  No MSMQ path name was specified (PROPID_Q_PATHNAME).

• MQ_ERROR_INVALID_OWNER
  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 MSMQ is not installed.

• 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 path name or instance already exists.

• MQ_ERROR_SERVICE_NOT_AVAILABLE
  Cannot connect to the Queue Manager.

• 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

For Windows Embedded CE, MQCreateQueue creates only local private queues. Also, security based on access-control lists (ACLs) is not supported.

By default, the MQCreateQueue function creates queues that have no journals. For these queues, you cannot activate message journaling using MQSetQueueProperties. To create a queue that has a journal, and to turn on journaling, set the PROPID_Q_JOURNAL property to MQ_JOURNAL.

To turn off journaling, call MQSetQueueProperties.

Before calling MQCreateQueue, specify the path name of the queue (PROPID_Q_PATHNAME).

The PROPID_Q_PATHNAMEproperty tells MSMQ the following:

• Where to store the queue's messages
• Whether the queue is public or private
• The name of the queue

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 a queue is created, its properties can be retrieved using MQGetQueueProperties and changed by calling MQSetQueueProperties.

The queue's returned format name is invalid if MQCreateQueue fails, including returning the error MQ_ERROR_QUEUE_EXISTS.

If the call returns MQ_INFORMATION_FORMATNAME_BUFFER_TOO_SMALL, the queue was created but the format name could not fit in the format name buffer.

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 returns an MQ_ERROR_QUEUE_EXISTS error when MQCreateQueue is called.

Requirements

See Also

Reference

aPropID
aPropVar
aStatus
MQCloseQueue
MQDeleteQueue
MQGetQueueProperties
MQOpenQueue
MQSetQueueProperties
PROPID_Q_JOURNAL_QUOTA
PROPID_Q_PATHNAME
MQQUEUEPROPS