Opening a Queue

Queues can be opened by calling the MSMQQueueInfo object's Open method. The Open method returns an MSMQQueue object that can be used for:

• Sending messages to the queue (Send).
  
  
• Enabling notification for reading messages asynchronously (EnableNotification)
  
  
• Reading messages in the queue (Peek, PeekNext, Receive)
  
  
• Closing the queue (Close)

Note The MSMQQueue object exposes a queue handle that can be used to call MSMQ API functions directly. For example, in Microsoft® Visual Basic®, MSMQ functions can be called directly using the Declare Function facility.

When opening a queue, the application specifies the access rights and share mode of the queue. The queue's access rights indicate if the application is going to send messages to the queue, peek at the messages in the queue, or retrieve messages from the queue. The queue's share mode indicates who else can use the queue while the application is using the queue.

In most cases, a queue can be opened without checking its access rights. However, if MQ_ERROR_ACCESS_DENIED is returned to the Open call, the queue's access control is blocking the application from opening the queue. A queue's access control can block sending messages, retrieving messages, or peeking at messages. For information about access rights, see Access Control.

The properties of the opened queue are based on the current properties of the MSMQQueueInfo object used to open the queue. While the queue is opened, the application can always see the current properties of the queue by calling the MSMQQueue object's queueInfo property.

To open a queue

1. Determine the queue's access mode. Are messages going to be sent to the queue (lAccess = MQ_SEND_ACCESS), retrieved from the queue(lAccess = MQ_RECEIVE_ACCESS), or peeked at without removing them from the queue (lAccess = MQ_PEEK_ACCESS)?

   When a queue is opened with receive access, the application can also peek at the queue's messages. However, the reverse is not true. When a queue is opened with peek access, the application cannot retrieve a message from the queue.

2. Determine the queue's share mode. If messages are going to be retrieved from the queue (lAccess = MQ_RECEIVE_ACCESS), determine if the application should not allow others to retrieve messages at the same time it is retrieving messages(ShareMode = MQ_DENY_RECEIVE_SHARE). Using this setting does not stop other applications from peeking at the messages in the queue, it only prevents them from retrieving messages at the same time the calling application is retrieving messages.
   
   
3. Verify that the queue information (MSMQQueueInfo) object exists and that a queue object (MSMQQueue) is available.
   
   
4. Call Open, setting the queue's access mode and share mode to the appropriate value.

Example: Opening a queue for sending messages

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 Declaration section of a form, and then run the example and click the form.

Dim qinfo As New MSMQQueueInfo
Dim q As New MSMQQueue

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

End Sub
 

Example: Opening a queue for reading messages

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

Dim qinfo As New MSMQQueueInfo
Dim q As New MSMQQueue

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

End Sub
 

© 1997 by Microsoft Corporation. All rights reserved.