MQOpenQueue

The MQOpenQueue function opens a queue for sending messages to the queue or for reading its messages.

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

Parameters

lpwcsFormatName

[in] Pointer to the format name string of the queue you want to open. The format name can be in a public, private, or direct format. See the Remarks section for details on direct 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.
MQ_RECEIVE_ACCESS: Messages can be looked at and removed from the queue. Whether a message is removed from the queue or looked at depends on the dwAction parameter of MQReceiveMessage.
See dwShareMode for limiting who can receive the messages.

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. If the queue is already opened for receiving messages by another process, this call fails and returns MQ_ERROR_SHARING_VIOLATION. Applicable only when dwAccess is set to MQ_RECEIVE_ACCESS or MQ_PEEK_ACCESS.

phQueue

[out] Handle to the opened queue.

Return Values

MQ_OK: Indicates success.
MQ_ERROR_ACCESS_DENIED: The calling process does not have the required access rights to open the queue with the access mode specified by dwAccess.
MQ_ERROR_ILLEGAL_FORMATNAME: The lpwcsFormatName parameter specified an illegal format name.
MQ_ERROR_NO_DS: Cannot access Active Directory.
MQ_ERROR_QUEUE_NOT_FOUND: (Public queues only) Queue is not registered in Active Directory.
MQ_ERROR_SERVICE_NOT_AVAILABLE: Cannot connect to the Queue Manager.
MQ_ERROR_INVALID_PARAMETER: One of the IN parameters is not valid.
MQ_ERROR_SHARING_VIOLATION: 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: The access mode specified by dwAccess is not supported. Set dwAccess to MQ_PEEK_MESSAGE, MQ_SEND_MESSAGE, or MQ_RECEIVE_MESSAGE and call MQOpenQueue again.
MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION: The lpwcsFormatName parameter specified a format name that is not supported by the access rights specified in dwAccess. See the following Remarks section for restrictions on using direct format names.

Remarks

If the format name of the queue is unknown, see Format Name to find ways to obtain a new format name.

Direct format names can only be used to open a queue for sending messages. A direct format name instructs MSMQ not to use Active Directory (for public queues) or the local computer (for private queues) to get routing information. When a direct format name is used to send messages, all routing information is derived from the provided format name and MSMQ sends the messages to the queue in a single hop.

Setting dwShareMode to MQ_DENY_RECEIVE_SHARE indicates that until the calling application calls MQCloseQueue, no other MSMQ applications can open a queue with receive access.

When opening a queue on a remote computer, MSMQ does not check for the existence of the queue when dwAccess is set to MQ_SEND_ACCESS. In addition, if dwAccess is set to MQ_RECEIVE_ACCESS, the computer opening the queue must support the same protocol as the remote computer where the queue is located.

Journal queues and dead letter queues can only be opened with dwAccess set to MQ_PEEK_ACCESS or MQ_RECEIVE_ACCESS. You cannot send messages to a journal queue.

Foreign queues cannot be opened using a direct format name. MSMQ needs the routing information stored in Active Directory to find an MSMQ Connector Sever for the foreign queue.

If the calling application does not have sufficient access rights to a queue, the following two things can happen:

If dwAccess is set to MQ_ACCESS_SEND, 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. 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	Queue Access Right
MQ_PEEK_MESSAGE	MQSEC_PEEK_MESSAGE
MQ_SEND_MESSAGE	MQSEC_WRITE_MESSAGE
MQ_RECEIVE_MESSAGE	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.

For Windows NT

For Windows NT, 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

A queue handle is not inherited by a child process.

Examples

For examples of using MQOpenQueue, see:

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mq.h.
  Import Library: Use mqrt.lib.
  Unicode: Defined only as Unicode.