3.1.4.2 R_OpenQueue (Opnum 2)

  • Article

The R_OpenQueue method opens a queue in preparation for subsequent operations against it. This method MUST be called prior to calling any of the following operations:

  • R_CreateCursor (Opnum 4) (section 3.1.4.4)

  • R_CloseCursor (Opnum 5) (section 3.1.4.5)

  • R_PurgeQueue (Opnum 6) (section 3.1.4.6)

  • R_StartReceive (Opnum 7) (section 3.1.4.7)

  • R_CancelReceive (Opnum 8) (section 3.1.4.8)

  • R_EndReceive (Opnum 9) (section 3.1.4.9)

  • R_MoveMessage (Opnum 10) (section 3.1.4.10) for the source queue only.

  • R_StartTransactionalReceive (Opnum 13) (section 3.1.4.13)

  • R_SetUserAcknowledgementClass (Opnum 14) (section 3.1.4.14)

  • R_EndTransactionalReceive (Opnum 15) (section 3.1.4.15)

This method returns a QUEUE_CONTEXT_HANDLE_SERIALIZE (section 2.2.4.2) handle value, which is required as input in the operations listed preceding.

 void R_OpenQueue(
   [in] handle_t hBind,
   [in] QUEUE_FORMAT* pQueueFormat,
   [in] DWORD dwAccess,
   [in] DWORD dwShareMode,
   [in] GUID* pClientId,
   [in] LONG fNonRoutingServer,
   [in] unsigned char Major,
   [in] unsigned char Minor,
   [in] USHORT BuildNumber,
   [in] LONG fWorkgroup,
   [out] QUEUE_CONTEXT_HANDLE_SERIALIZE* pphContext
 );

hBind: MUST specify an RPC binding handle parameter, as specified in [MS-RPCE] section 2.

pQueueFormat: MUST be a pointer to a QUEUE_FORMAT ([MS-MQMQ] section 2.2.7) structure that identifies the queue to open. NULL is invalid for this parameter. The valid values for the m_qft member are QUEUE_FORMAT_TYPE_PUBLIC, QUEUE_FORMAT_TYPE_PRIVATE, QUEUE_FORMAT_TYPE_DIRECT, QUEUE_FORMAT_TYPE_MACHINE, and QUEUE_FORMAT_TYPE_SUBQUEUE.

dwAccess: Specifies the requested type of access to the queue. The required dwAccess parameter value for each event is specified in each of the corresponding events. If no requirement is listed, any dwAccess parameter value is accepted.

Value

Meaning

RECEIVE_ACCESS

0x00000001

The returned QUEUE_CONTEXT_HANDLE_SERIALIZE handle can be used in the R_StartReceive or R_StartTransactionalReceive methods with the ulAction parameter set to either a Peek or Receive action type as defined in the table under the ulAction parameter in the R_StartReceive method.

PEEK_ACCESS

0x00000020

The returned QUEUE_CONTEXT_HANDLE_SERIALIZE handle can be used in the R_StartReceive method with the ulAction parameter set only to a Peek action type as defined in the table under the ulAction parameter in the R_StartReceive method.

dwShareMode: Specifies whether the client needs exclusive access to the queue. The following values are valid for this parameter:

Value

Meaning

MQ_DENY_NONE

0x00000000

Permits multiple QUEUE_CONTEXT_HANDLE_SERIALIZE handles to the queue to be opened concurrently.

MQ_DENY_SHARE

0x00000001

Permits a single QUEUE_CONTEXT_HANDLE_SERIALIZE handle to the queue at a time, providing exclusive access to the queue.

pClientId: MUST be set by the client to a pointer to a valid GUID that uniquely identifies the client. When the queue manager acts as the client, the queue manager sets this value to the Identifier ADM attribute of the local QueueManager ADM element instance. The server SHOULD ignore this parameter. The server MAY<14> use this parameter to impose a limit on the number of unique callers. NULL is invalid for this parameter.

fNonRoutingServer: If the client is configured to operate in the role of an MSMQ routing server, this parameter MUST be set to FALSE (0x00000000); otherwise, it MUST be set to TRUE (0x00000001).<15> If the value of the fNonRoutingServer parameter is FALSE (0x00000000), the server MUST ignore the pClientId parameter.

Name

Value

False

0x00000000

True

0x00000001

Major: MUST be set by the client to an implementation-specific Major Version number of the client. SHOULD<16> be ignored by the server.

Minor: MUST be set by the client to an implementation-specific Minor Version number of the client. SHOULD<17> be ignored by the server.

BuildNumber: MUST be set by the client to an implementation-specific Build Number of the client. SHOULD<18> be ignored by the server.

fWorkgroup: MUST be set to TRUE (0x00000001) by the client if the client machine is not a member of a Windows domain; otherwise, it MUST be set to FALSE (0x00000000). The RPC authentication level required by the server MAY<19> be based on this value in subsequent calls on the interface.

Name

Value

False

0x00000000

True

0x00000001

pphContext: MUST be set by the server to a QUEUE_CONTEXT_HANDLE_SERIALIZE handle.

Return Values: The method has no return values. If the method fails, an RPC exception is thrown.

Exceptions Thrown:

In addition to the exceptions thrown by the underlying RPC protocol, as specified in [MS-RPCE], the method throws HRESULT failure codes as RPC exceptions. The client MUST treat all thrown HRESULT codes identically. The client MUST disregard all output parameter values when any failure HRESULT is thrown.

When processing this call, the server MUST do the following:

  • If any of the input parameter values is invalid, throw MQ_ERROR_INVALID_PARAMETER (0xC00E0006).

  • Look up the queue name in the QueueCollection ADM attribute of the local QueueManager ADM element instance. If not found, throw MQ_ERROR_QUEUE_NOT_FOUND (0xC00E0003).

  • Generate an Open Queue ([MS-MQDMPR] section 3.1.7.1.5) event with the following inputs:

    • iFormatName := pQueueFormat

    • iRequiredAccess := If the dwAccess parameter is RECEIVE_ACCESS then QueueAccessType.ReceiveAccess else QueueAccessType.PeekAccess.

    • iSharedMode := If the dwShareMode parameter is MQ_DENY_NONE then QueueShareMode.DenyNone else QueueShareMode.DenyReceive.

  • If rStatus is MQ_OK (0x00000000):

    • Set the pphContext parameter to rOpenQueueDescriptor.Handle