MQOpenQueue

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function opens a queue for sending messages to the queue or for reading its messages.

Syntax

HRESULT APIENTRY MQOpenQueue(
  LPCWSTR lpwcsFormatName,
  DWORD dwAccess,
  DWORD dwShareMode,
  LPQUEUEHANDLE phQueue
);

Parameters

• lpwcsFormatName
  [in] Pointer to the format name string of the queue you want to open.

  The format name must be in the private direct format.

  For restrictions on the different types of format names, See the Remarks section.

• dwAccess
  [in] Specifies how the application accesses the queue (peek, send, or receive). This setting cannot be changed while the queue is open.

  Specify one of the following access modes.

  Value	Description
  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 looked at and removed from the queue. Whether a message is removed from the queue or looked at depends on the dwAction parameter of MQReceiveMessage.

• dwShareMode
  [in] How the queue will be shared.

  Specify one of the following values.

  Value	Description
  MQ_DENY_NONE	Default. The queue is available to everyone. You must use this setting if dwAccess is set to MQ_SEND_ACCESS.
  MQ_DENY_RECEIVE_SHARE	Limits those who can receive messages from the queue to this process. If the queue is opened for receiving messages by another process, this call fails and returns MQ_ERROR_SHARING_VIOLATION. Applicable only when dwAccess is set to MQ_RECEIVE_ACCESS or MQ_PEEK_ACCESS.

• phQueue
  [out] Handle to the opened queue.

Return Value

• MQ_OK
  Indicates success.

• MQ_ERROR_ACCESS_DENIED
  The calling process does not have the required access rights to open the queue with the access mode specified by dwAccess.

• MQ_ERROR_ILLEGAL_FORMATNAME
  The lpwcsFormatName parameter specified an illegal format name.

• MQ_ERROR_QUEUE_NOT_FOUND
  (Public queues only.) Queue is not registered in Microsoft® Active Directory™.

• MQ_ERROR_SERVICE_NOT_AVAILABLE
  Cannot connect to the Queue Manager.

• MQ_ERROR_INVALID_PARAMETER
  One IN parameter is not valid.

• MQ_ERROR_SHARING_VIOLATION
  Another process opened this queue with dwShareMode set to MQ_DENY_RECEIVE_SHARE, or another process opened the queue for receive so you cannot specify MQ_DENY_RECEIVE_SHARE.

• MQ_ERROR_UNSUPPORTED_ACCESS_MODE
  The access mode parameter (dwAccess) is set to an invalid value, or dwAccess is set to MQ_SEND_MESSAGE and the share mode parameter (dwShareMode) is set to MQ_DENY_RECEIVE_SHARE.

• MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION
  The format name specified in the lpwcsFormatName parameter cannot be used.

  If dwAccess is set to MQ_PEEK_ACCESS or MQ_RECEIVE_ACCESS, direct format names cannot be used.

  For details, see the Remarks section.

  If dwAccess is set to MQ_SEND_ACCESS, format names that reference journal, dead-letter, or connector queues cannot be used.

Remarks

MQOpenQueue opens queues using only the private direct format name. If the format name is correct and disk space is sufficient, it never fails opening the outgoing queue.

To open a remote transactional queue, append XACTONLY to the end of the format name. For example, FORMAT=remotemachine\private$\transactionalqueue;XACTONLY is marked as transactional for all subsequent open operations.

The XACTONLY flag is required because Active Directory lookup is not supported in Windows Embedded CE, so there is no way to check if the remote queue is transactional. However, the flag is always ignored when opening local queues.

When opening a queue to send messages to a remote computer (when dwAccess is set to MQ_SEND_ACCESS), MSMQ 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 resides.

To read messages from a queue on a remote computer, there must be a direct connection between the computers.

You cannot use a direct format name to open a queue to read messages. Direct format names can only be used if dwAccess is set to MQ_SEND_ACCESS. When using a direct format name to send a message, all routing information is derived from the format name and MSMQ sends the messages to the queue in a single hop.

You cannot open a journal queue to send messages. Journal queues can only be opened with peek or receive access.

Setting dwShareMode to MQ_DENY_RECEIVE_SHARE indicates that until the calling application calls MQCloseQueue, no other MSMQ applications can open a queue with receive access.

If the calling application does not have sufficient access rights to a queue, the following can happen:

• If dwAccess is set to MQ_ACCESS_SEND, MQOpenQueue succeeds, but errors are returned when the application tries to send a message.
• If dwAccess is set to MQ_PEEK_ACCESS or MQ_RECEIVE_ACCESS, MQOpenQueue fails and returns MQ_ERROR_ACCESS_DENIED. In this case, a queue handle is not returned to phQueue.

There is no provision to change the access mode of the queue when it is open. Either close and open the queue with the chosen access mode, or open a second instance of the queue.

Requirements

See Also

Reference

MQCloseQueue
MQReceiveMessage