MSMQQueueInfo.Open

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method opens a queue for sending, peeking at, or retrieving messages. The properties of the queue are based on the current properties of the MSMQQueueInfo object.

Syntax

HRESULT Open( 
  long Access, 
  long ShareMode, 
  MSMQQueue** ppq
);

Parameters

• Access
  Specifies how the application accesses the queue, whether to peek, send, or receive. This setting cannot be changed while the queue is open.

  Access can be set to one of the following values:

  • 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. For information on limiting who can retrieve messages from the queue, see the description of the ShareMode parameter.

• ShareMode
  Specifies who can access the queue. ShareMode can be 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 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.

• ppq
  Queue to open.

Return Value

The following table describes the common return values.

Remarks

MSMQQueueInfo.Open returns an MSMQQueue object each time 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.

Queue access rights

If the calling application does not have sufficient access rights to a queue, 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.

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.

After opening a queue, there is no provision to change the access mode of the queue.

Opening queues on remote computers

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.

Opening journal, dead-letter, and connector queues

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.

Opening foreign queues

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

Setting share mode

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 might have the correct access rights to read messages from the queue.

Direct format names

Direct format names can only be used when sending messages to a queue.

A direct format name tells Message Queuing not to use the directory service 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 Message Queuing sends the messages to the queue in a single hop.

Requirements