MSMQQueueInfo.Open (Windows CE 5.0)
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.
HRESULT Open( longAccess,longShareMode,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 Values
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.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.
| 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 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
OS Versions: Windows CE .NET 4.0 and later.
Header: Mqoai.h.
Link Library: Mqoa.lib.
Send Feedback on this topic to the authors