MQOpenQueue

 

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 MQOpenQueue function opens a queue for sending, peeking at, retrieving, or purging messages. The function can also be used to open a sub queue. For information about sub queues see Subqueues.

HRESULT APIENTRY MQOpenQueue(  
  LPCWSTR lpwcsFormatName,    
  DWORD dwAccess,          
  DWORD dwShareMode,       
  QUEUEHANDLE * phQueue    
);  

Parameters

lpwcsFormatName

[in] Pointer to the format name string of the queue you want to open. The string can contain a single-element format name or, in MSMQ 3.0, a multiple-element format name. Single-element format names include public, private, direct, distribution list, machine, or connector format names. Multiple-element format names can contain one or more single-element format names.

dwAccess

[in] Specifies how the application accesses the queue (peek, send, or receive). This setting cannot be changed while the queue is open.

Specify one of the following access modes:

MQ_PEEK_ACCESS

Messages can only be looked at. They cannot be removed from the queue.

MQ_SEND_ACCESS

Messages can only be sent to the queue. A subqueue cannot be opened using this access mode.

MQ_MOVE_ACCESS

Can be used only with a subqueue. Requires the user to have peek permission for the queue.

MQ_RECEIVE_ACCESS

Messages can be retrieved (read and removed) from the queue, peeked at, or purged. Whether a message is removed from the queue in a call to MQReceiveMessage depends on the dwAction parameter of this function.

See the description of the dwShareMode parameter for information on limiting who can receive messages from the queue.

MQ_PEEK_ACCESS | MQ_ADMIN_ACCESS

Messages in the local outgoing queue can only be peeked at (read without being removed from the queue).

MQ_RECEIVE_ACCESS | MQ_ADMIN_ACCESS

Messages in the local outgoing queue can be retrieved (read and removed from the queue), peeked at (read without being removed from the queue), or purged (deleted).

Note MQ_ADMIN_ACCESS is used to access messages in a local outgoing queue, rather than the corresponding remote destination queue.

dwShareMode

[in] How the queue will be shared. Specify one of the following:

MQ_DENY_NONE

Default. The queue is available to everyone. This setting must be used if dwAccess is set to MQ_SEND_ACCESS.

MQ_DENY_RECEIVE_SHARE

Limits those who can receive messages from the queue to this process. Once a process opens a queue with this share mode and with dwAccess set to MQ_RECEIVE_ACCESS, no one else, including the process that opened the queue, can open it again to peek or receive messages (this includes attempting to open the queue with multiple threads within the same process) until the original caller closes the queue. However, inside the process, the returned queue handle can be used by several threads.

Once the queue is opened with this share mode and with dwAccess set to MQ_RECEIVE_ACCESS, the MQ_ERROR_SHARING_VIOLATION error is returned when a second attempt is made to open the queue to peek or receive messages.

phQueue

[out] Pointer to a handle to the opened queue. If MQOpenQueue fails, a NULL pointer is returned.

Note The Access modes MQ_PEEK_ACCESS, MQ_RECEIVE_ACCESS and MQ_MOVE_ACCESS are the only access modes that can be used while opening a subqueue.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_ACCESS_DENIED (0xC00E0025)

The access rights for opening the queue with the access mode specified by dwAccess are not allowed for the calling process.

Note A user cannot open a subqueue for MQ_MOVE_ACCESS unless the user has MQSEC_PEEK_MESSAGE permission on the queue. If the user does not have this permission, the call to MQOpenQueue fails with MQ_ERROR_ACCESS_DENIED if the queue is local. If the queue is remote, the call fails with 0x80070005 (access denied).

MQ_ERROR_ILLEGAL_FORMATNAME (0xC00E001E)

The lpwcsFormatName parameter specified an illegal format name.

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

One of the IN parameters is not valid.

MQ_ERROR_NO_DS (0xC00E0013)

A connection with the directory service cannot be established. Verify permissions for accessing the directory service.

MQ_ERROR_QUEUE_NOT_FOUND (0xC00E0003)

Message Queuing cannot find the queue. The queue may be a public queue not registered in the directory service or an Internet queue that does not exist in the MSMQ namespace.

MQ_ERROR_REMOTE_MACHINE_NOT_AVAILABLE (0xC00E0069)

The remote computer that hosts the queue being opened for reading messages is not available.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

MQ_ERROR_SHARING_VIOLATION (0xC00E0009)

Another process already opened this queue with dwShareMode set to MQ_DENY_RECEIVE_SHARE, or another process has already opened the queue for receive so you can't specify MQ_DENY_RECEIVE_SHARE.

MQ_ERROR_UNSUPPORTED_ACCESS_MODE (0xC00E0045)

The access mode parameter (dwAccess) is set to an invalid value, or dwAccess is set to MQ_SEND_ACCESS and the share mode parameter (dwShareMode) is set to MQ_DENY_RECEIVE_SHARE.

MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION (0xC00E0020)

The format name specified in the lpwcsFormatName parameter cannot be used.

Direct format names cannot be used if dwAccess is set to MQ_PEEK_ACCESS or MQ_RECEIVE_ACCESS. See the following Remarks section for details.

Format names that reference journal, dead-letter, or connector queues cannot be used if dwAccess is set to MQ_SEND_ACCESS.

Remarks

The MQOpenQueue function can be used to open queues for sending or reading messages. When opening queues to send messages the application can specify a one queue or several queues. When opening a queue to read messages the application can only specify one queue.

To open multiple queues, the application can specify a distribution list format name or multiple-element format name in the lpwcsFormatName parameter.

The main difference between distribution lists and multiple element format names is that distribution lists are public lists that are published in Active Directory Domain Services (AD DS) and multiple-element format names are private lists that are created and maintained at the application level.

For information on distribution lists and multiple-element format names, see Multiple-Destination Messaging.

When opening a queue to send messages to a remote computer (when dwAccess is set to MQ_SEND_ACCESS), Message Queuing does not check for the existence of the queue.

When opening a queue to read messages from a remote computer (when dwAccess is set to MQ_RECEIVE_ACCESS or MQ_PEEK_ACCESS), the computer opening the queue must support the same protocol as the remote computer where the queue resides. To read messages from a queue on a remote computer, there must be a direct connection between the two computers.

If the format name of the queue is unknown, see Obtaining Format Names.

For MSMQ 1.0 prior to Windows NT 4.0 SP6, you cannot use a direct format name to open a queue to read messages, and direct format names can only be used if dwAccess is set to MQ_SEND_ACCESS.

In all later versions of MSMQ, direct format names can be used for any queue when sending or receiving messages.

A direct format name prevents Message Queuing from using the directory service (for remote public queues) or the local computer (for private queues) to obtain routing information. When a direct format name is used to send a message, all routing information is derived from the format name, and Message Queuing sends the message to the queue in a single hop. Nevertheless, in any call to open a local public queue, Message Queuing always attempts to contact directory service and update the data in the local information cache. If the directory service cannot be accessed, the information in the local cache is used.

In workgroup mode, you can use direct format names to open any public or private queue for sending messages or to open local and remote private queues for reading messages.

When an application opens a local outgoing queue to retrieve, peek at, or purge messages, the format name set in the lpwcsFormatName parameter must be exactly the same as the format name used when the corresponding remote destination queue was opened to send the messages. If messages are sent to a given remote destination queue using two different format names, for example, PUBLIC=1860FD46-0356-11D3-A17C-0080C7199D3E and DIRECT=OS:MIKE01\Q2, two different outgoing queues are created, and each can be accessed using the corresponding format name.

Local administrative permissions are required to open an outgoing queue.

If the access rights for opening the queue in the mode requested are not allowed for the calling application, the following two things can happen:

• If dwAccess is set to MQ_SEND_ACCESS, MQOpenQueue will succeed, but errors will be returned when the application tries to send a message.

• If dwAccess is set to MQ_PEEK_ACCESS or MQ_RECEIVE_ACCESS, MQOpenQueue will fail and return MQ_ERROR_ACCESS_DENIED (0xC00E0025). In this case a queue handle is not returned to phQueue.

To change the access rights of the queue, call MQSetQueueSecurity. The following table lists the access right needed to open the queue in peek, send, or receive access mode.

Queue Access Mode Requested	Queue Access Right Required
MQ_PEEK_ACCESS	MQSEC_PEEK_MESSAGE
MQ_SEND_ACCESS	MQSEC_WRITE_MESSAGE
MQ_RECEIVE_ACCESS	MQSEC_RECEIVE_MESSAGE

There is no provision to change the access mode of the queue when it is open. Either close and open the queue with the desired access mode, or open a second instance of the queue.

You cannot open a queue journal, computer journal, dead-letter queue or connector queue with dwAccess set to MQ_SEND_ACCESS. These queues are system queues and can be opened only with dwAccess set to MQ_PEEK_ACCESS or MQ_RECEIVE_ACCESS.

Foreign queues cannot be opened using a direct format name. Message Queuing needs the routing information stored in the directory service to find the appropriate connector server for the foreign queue.

Setting dwShareMode to MQ_DENY_RECEIVE_SHARE indicates that until the calling application calls MQCloseQueue, no other Message Queuing applications can open a queue with receive access. This includes applications that may be allowed the correct access rights to read messages from the queue.

For Windows NT, Windows® 2000, and newer versions of Windows, a queue handle is always inherited by a child process. If a child process is created by the process that opened the queue, the queue handle is inherited by the child process.

For Windows 95 (with IE302 or later installed), a queue handle is not inherited by a child process.

The following internal private queues are used by Message Queuing and cannot be opened by applications:

• admin_queue$

• order_queue$

• notify_queue$

Equivalent COM Method

When using COM components, you can open a queue (create an open instance of the queue) for sending, peeking at, retrieving, or purging the messages in it by calling the MSMQQueueInfo.Open method.

Example Code

The following code examples are included in Using Message Queuing.

For an example of	See
Opening a destination queue to send or read messages	C/C++ Code Example: Opening a Queue
Opening a queue when only the queue's identifier (GUID) is known	C/C++ Code Example: Opening a Queue Using a Queue Identifier
Opening a private queue when only the computer identifier (GUID) and queue number is known	C/C++ Code Example: Opening a Private Queue Using a Computer Identifier and Queue Number
Opening dead-letter queues to read undelivered messages	C/C++ Code Example: Reading Messages in the Dead-Letter Queue

Reading Messages in the Transactional Dead-Letter 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 Mq.h.

Library: Use Mqrt.lib.

See Also

Message Queuing Functions
MQCloseQueue
MQReceiveMessage
MQSetQueueSecurity