MSMQQueueInfo.Open
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 Open method of the MSMQQueueInfo object opens a queue for sending, peeking at, retrieving, or purging messages and creates a cursor for navigating the queue if the queue is being opened for retrieving messages.
The properties of the queue are based on the current properties of the queue information (MSMQQueueInfo) object.
Function Open( _
ByVal Access As Long, _
ByVal ShareMode As Long _
)
Parameters
Access
[in] Long. Specifies how the application accesses the queue (peek, send, or receive). This setting cannot be changed while the queue is open.
Access can be set to one of the following:
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 retrieved (read and removed) from the queue, peeked at, or purged. See the description of the ShareMode argument for information on limiting who can retrieve 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.
ShareMode
[in] Long. Specifies who can access the queue. Set to one of the following:
MQ_DENY_NONE: Default. The queue is available to all members of the Everyone group. This setting must be used if Access is set to MQ_PEEK_ACCESS or MQ_SEND_ACCESS.
MQ_DENY_RECEIVE_SHARE: Limits those who can retrieve messages from the queue to this process. If the queue is already opened for retrieving messages by another process, this call fails and an MQ_ERROR_SHARING_VIOLATION (0xC00E0009) error is generated. Applicable only when Access is set to MQ_RECEIVE_ACCESS.
Return Values
An MSMQQueue object that represents the instance of the queue opened (in C++, a smart pointer to the IMSMQQueue interface).
Error Codes
For information on return codes, see Message Queuing Error and Information Codes.
Remarks
Open returns an MSMQQueue object each time that it is called. There is a one-to-many relationship between the MSMQQueueInfo object that represents the queue and the MSMQQueue objects that represent an open instance of the queue.
An MSMQQueueInfo object can be initialized to reference a specific queue before calling the Open method by setting its MSMQQueueInfo.FormatName or MSMQQueueInfo.PathName property. However, the FormatName property must be set with a direct format name to open a remote private queue.
Setting the FormatName property of a public queue instead of the PathName property frees Message Queuing from the need to retrieve information stored in the directory service to generate a format name from the path name of a public queue. Computers operating in offline mode cannot access the directory service and obtain the information needed to generate the format name of a public queue. Computers that belong to a workgroup can only generate the format name of a local private queue.
Direct format names can be used for any queue when sending or receiving messages.
Note
Direct format names that specify the HTTP or HTTPS protocol cannot be used to peek at or receive messages, only to send them.
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, all routing information is derived from the format name and Message Queuing sends or receives the message in a single hop. Nevertheless, in any call to open a local public queue, Message Queuing always attempts to contact the 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.
To open multiple queues, call MSMQDestination.Open. For information on opening multiple queues using distribution lists, multicast addresses, and multiple-element format names, see Multiple-Destination Messaging.
When an application opens a local outgoing queue to retrieve, peek at, or purge messages, the format name set in the FormatName property must be exactly the same as the format name set 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 access mode requested are not allowed for the calling application, the following two things can happen:
If Access is set to MQ_SEND_ACCESS, Open succeeds, but errors are thrown when the application tries to send a message.
If Access is set to MQ_PEEK_ACCESS or MQ_RECEIVE_ACCESS, Open fails and throws MQ_ERROR_ACCESS_DENIED (0xC00E0025).
To change the access rights of the queue, call MQSetQueueSecurity. The following table lists the access rights needed to open the queue in peek, send, or receive access mode.
| Queue Access Mode Requested | Queue Access Rights Required |
|---|---|
| MQ_PEEK_ACCESS | MQSEC_PEEK_MESSAGE |
| MQ_SEND_ACCESS | MQSEC_WRITE_MESSAGE |
| MQ_RECEIVE_ACCESS | MQSEC_RECEIVE_MESSAGE |
After opening a queue, there is no provision to change the access mode of the queue.
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 is located. To read messages from a queue on a remote computer, there must be a direct connection between both computers.Sending applications cannot open journal queues, dead-letter queues, or connector queues for sending messages. These queues can only be opened with Access 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 an MSMQ connector server for the foreign queue.
Setting ShareMode to MQ_DENY_RECEIVE_SHARE means that until the calling application calls the MSMQQueue object's MSMQQueue.Close method, no other Message Queuing applications can read the messages in the queue. This includes applications that may be allowed the correct access rights to read messages from the queue.
Equivalent Function
The MQOpenQueue function is used to open queues in function calls.
Example Code
The following examples are included in Using Message Queuing.
| For an example of | See |
|---|---|
| Opening a destination queue using a public or private format name | C++ COM Code Example: Opening a Queue Visual Basic Code Example: Opening a Queue VBScript Code Example: Opening a Queue |
| Opening the computer journal to read messages | Visual Basic Code Example: Reading Messages in the Computer Journal |
| Opening a dead-letter queue to read messages | Visual Basic Code Example: Reading Messages in the Dead-Letter Queue |
| Opening a transactional dead-letter queue to read messages | Visual Basic Code Example: Reading Messages in the Transactional Dead-Letter Queue |
| Opening a queue journal to read messages | Visual Basic Code Example: Reading Messages in a Queue Journal |
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 Mqoai.h.
Library: Use Mqoa.lib.