Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
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 MSMQQueueInfoobject.

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.

Accesscan 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. ShareModecan 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.

Value Description

S_OK

Success

E_INVALIDARG

One or more arguments are invalid

E_NOTIMPL

The function contains no implementation

E_OUTOFMEMORY

Out of memory

Remarks

MSMQQueueInfo.Openreturns an MSMQQueueobject each time it is called.

There is a one-to-many relationship between the MSMQQueueInfoobject that represents the queue and the MSMQQueueobjects 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.

Queue access mode Queue access right

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.

Opening queues on remote computers

When opening a queue to send messages to a remote computer (when dwAccessis 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 dwAccessis 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 Accessset 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 ShareModeto MQ_DENY_RECEIVE_SHARE means that until the calling application calls the MSMQQueueobject's MSMQQueue.Closemethod, 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

Header mqoai.h
Library mqoa.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later