Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
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 MQQUEUEPROPSstructure (default values are used for all properties that are not specified) are attached to the queue.

MQCreateQueuereturns 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 MQQUEUEPROPSstructure that specifies the properties of the queue.

On input, the following occurs:

  • The cPropmember of MQQUEUEPROPSspecifies the number of queue properties supplied.

  • The aPropIDarray specifies their property identifiers.

  • The aPropVararray specifies their values.

On output, the optional aStatusarray, 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 lpwcsFormatNamebuffer (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_PATHNAMEcontains 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, MQCreateQueuecreates only local private queues. Also, security based on access-control lists (ACLs) is not supported.

By default, the MQCreateQueuefunction 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_JOURNALproperty 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 pQueuePropsparameter, MSMQ uses its default value when creating the queue.

After a queue is created, its properties can be retrieved using MQGetQueuePropertiesand changed by calling MQSetQueueProperties.

The queue's returned format name is invalid if MQCreateQueuefails, 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 MQCreateQueueis called.

Note:
OS versions prior to 2.12 require the MSMQ add-on pack.

Requirements

Header mq.h
Library msmqrt.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later
Note Versions prior to 2.12 require the MSMQ add-on pack

See Also