Open
MSMQQueueInfo

The Open method opens a queue for sending messages to the queue, for reading messages in the queue (peek and receive access), or for looking at queue's information.

The properties of the queue are based on the current properties of the queue information (MSMQQueueInfo) object.

Syntax

set object2 = object1.Open (Access, ShareMode)

Syntax Element	Description
object1	Queue information (MSMQQueueInfo) object that defines the queue.
object2	Queue (MSMQQueue) object that represents the open instance of the queue.
Access	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 from the queue or peeked at. See ShareMode for limiting who can retrieve messages.
ShareMode	Specifies who can access the queue. Set to one of the following: MQ_DENY_NONE: Default. The queue is available to everyone. 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 returns MQ_ERROR_SHARING_VIOLATION. Applicable only when Access is set to MQ_RECEIVE_ACCESS.

Return Codes

For information on return codes, see MSMQ Error and Information Codes.

Remarks

Open returns an MSMQQueue object each time it is called. Consequently, the MSMQQueueInfo object that opens the queue can be associated with any number of MSMQQueue objects.

When the queue is opened, Active Directory is automatically updated with the current property values of the MSMQQueueInfo object.

When a queue is opened, the cursor points to the front of the queue, not the first message in the queue. For information on how to move the cursor to the first message in the queue, see MSMQQueue.

Direct format names can only be used when sending messages to a queue. A direct format name tells 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, all routing information is taken from the format name and MSMQ sends the messages to the queue in a single hop.

Setting ShareMode to MQ_DENY_RECEIVE_SHARE means that until the calling application calls the MSMQQueue object's Close method, no other MSMQ applications can read the messages in the queue. This includes applications that may have the correct access rights to read messages from the queue.

If the calling application does not have sufficient access rights to a queue, two things can happen. If Access is set to MQ_PEEK_ACCESS or MQ_RECEIVE_ACCESS, Open fails and throws MQ_ERROR_ACCESS_DENIED. If Access is set to MQ_ACCESS_SEND, Open succeeds, but errors are thrown when the application tries to send a message.

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	Queue Access Right
MQ_PEEK_MESSAGE	MQSEC_PEEK_MESSAGE
MQ_SEND_MESSAGE	MQSEC_WRITE_MESSAGE
MQ_RECEIVE_MESSAGE	MQSEC_RECEIVE_MESSAGE

After opening a queue, there is no provision to change the access mode of the queue. Either close and open the queue in the current thread, or open a new thread with new access rights.

When the queue is opened, Active Directory is automatically updated with the current property values of the MSMQQueueInfo object.

When a queue is opened, the cursor points to the front of the queue, not the first message in the queue. For information on how to move the cursor to the first message in the queue, see Reading Messages In a Queue.

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

When opening a queue on a remote computer, MSMQ does not check for the existence of the queue when Access is set to MQ_SEND_ACCESS. In addition, if Access 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.

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

Example

This example creates a public queue, then opens the queue for sending messages. To try this example using Microsoft® Visual Basic® (version 5.0), paste the code into the Code window of a form, run the example, and click the form.

Dim qinfo As MSMQQueueInfo
Dim q As MSMQQueue

Private Sub Form_Click()
    
  Set qinfo = New MSMQQueueInfo
  qinfo.PathName = ".\OpenTest"
  qinfo.Label = "Test Queue"
  qinfo.Create
  
  Set q = qinfo.Open(MQ_SEND_ACCESS, MQ_DENY_NONE)
  If q.IsOpen Then
     MsgBox "The queue " + qinfo.PathName + " is open."
     Else
     MsgBox "The queue is not open!"
  End If

End Sub

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in resapi.h.