3.1.4.2 R_QMOpenRemoteQueue (Opnum 2)

  • Article

A client calls R_QMOpenRemoteQueue to obtain a valid queue handle on a remote queue as part of the sequence of events involved in opening a remote queue as described in section 4.2.

 HRESULT R_QMOpenRemoteQueue(
   [in] handle_t hBind,
   [out] PCTX_OPENREMOTE_HANDLE_TYPE* pphContext,
   [out] DWORD* pdwContext,
   [in, unique] QUEUE_FORMAT* pQueueFormat,
   [in] DWORD dwCallingProcessID,
   [in] DWORD dwDesiredAccess,
   [in] DWORD dwShareMode,
   [in] GUID* pLicGuid,
   [in] DWORD dwMQS,
   [out] DWORD* dwpQueue,
   [out] DWORD* phQueue
 );

hBind:  MUST be set to an RPC binding handle as described in [MS-RPCE] section 2.

pphContext:  A pointer to a variable to receive the PCTX_OPENREMOTE_HANDLE_TYPE (section 2.2.1.1.3) context handle.

pdwContext: A pointer to a variable to receive the value of the Handle attribute for the new OpenQueueDescriptor ([MS-MQDMPR] section 3.1.1.16) ADM element instance created by this method. It MUST NOT be NULL.

pQueueFormat: A QUEUE_FORMAT ([MS-MQMQ] section 2.2.7) structure that identifies the queue to be opened. It MUST NOT be NULL and MUST conform to the format name syntax rules defined in [MS-MQMQ]. It MUST NOT be a distribution list or multicast format name. For direct format names, the protocol MUST NOT be HTTP.

dwCallingProcessID:  MUST be ignored. Clients MAY pass 0x00000000.<15>

dwDesiredAccess:  A DWORD that specifies the access mode requested for the queue. The access mode defines the set of operations that can be invoked using the returned queue handle. The value MUST be one of the following:

Value

Meaning

MQ_RECEIVE_ACCESS

0x00000001

The returned queue handle MUST only permit message peek, message receive (peek and delete), and queue purge operations.

MQ_PEEK_ACCESS

0x00000020

The returned queue handle MUST only permit message peek operations.

dwShareMode:  Specifies the exclusivity level for the opened queue. The value MUST be one of the following:

Value

Meaning

MQ_DENY_NONE

0x00000000

The queue is not opened exclusively.

MQ_DENY_RECEIVE_SHARE

0x00000001

The queue is to be opened for exclusive read access. If the queue has already been opened for read access, the server MUST return STATUS_SHARING_VIOLATION (0xc0000043). If the queue is opened successfully for exclusive read access, subsequent attempts to open the same queue for read access MUST return STATUS_SHARING_VIOLATION (0xc0000043) until the queue has been closed.

pLicGuid:  MUST be a pointer to a valid GUID that uniquely identifies the client.<16><17> The server MAY ignore this parameter.<18>

dwMQS:  MUST be set by clients to indicate the client operating system category. Servers MAY ignore this value.<19> The following values are defined:

Value

Are server connection licensing limitations enforced?/Meaning

0x00000000<20>

None. The operating system (OS) version is not declared.

0x00000100

Yes. For supported operating systems.<21>

0x00000200

Yes. For supported operating systems.<22>

0x00000300

Yes. For supported operating systems.<23>

0x00000400

No. For supported operating systems.<24>

0x00000500

No. For supported operating systems.<25>

dwpQueue: A pointer to a variable to receive a value that identifies the new OpenQueueDescriptor ADM element instance created by this method, as specified in the processing rules section for this method. It MUST NOT be NULL.

phQueue: A pointer to a variable to receive the value of the Handle attribute for the new OpenQueueDescriptor ADM element instance created by this method. It MUST NOT be NULL.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT <26>, and the client MUST treat all failure HRESULTs identically. Additionally, if a failure HRESULT is returned, the client MUST disregard all out-parameter values.

Exceptions Thrown: In addition to the exceptions thrown by the underlying RPC protocol [MS-RPCE], the method can throw HRESULT failure codes as RPC exceptions. The client MUST treat all thrown HRESULT codes identically. Additionally, the client MUST disregard all out-parameter values when any failure HRESULT is thrown.

This method is invoked at the dynamically assigned endpoint returned by the R_QMGetRTQMServerPort method when IP_HANDSHAKE (0x00000000) or IPX_HANDSHAKE (0x00000002) is the interface specified by the fIP parameter.

When processing this call, the server MUST:

  • Determine if input parameter values violate constraints specified above. If an invalid parameter is detected, the server MUST take no further action and return a failure HRESULT.

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

    • iFormatName := pQueueFormat

    • iRequiredAccess :=dwDesiredAccess, according to the following values:

      • MQ_RECEIVE_ACCESS (0x00000001): ReceiveAccess

      • MQ_PEEK_ACCESS (0x00000020): PeekAccess

    • iSharedMode := dwShareMode, according to the following values:

      • MQ_DENY_NONE (0x00000000): DenyNone

      • MQ_DENY_RECEIVE_SHARE (0x00000001): DenyReceive

  • If the rStatus out-argument of the Open Queue event indicates failure, take no further action and return the rStatus value.

  • The rOpenQueueDescriptor out-argument of the Open Queue event contains a reference to the OpenQueueDescriptor ADM element instance created by the Open Queue event.

  • Set rOpenQueueDescriptor.RemoteReadState to Opened.

  • Declare iNewRemoteQueueOpenContextHandle as a RemoteQueueOpenContextHandle ADM element instance and set its attributes to the following values:

    • Handle := PCTX_OPENREMOTE_HANDLE_TYPE reference to rOpenQueueDescriptor.Handle.

    • OpenQueueDescriptorReference := The rOpenQueueDescriptor out-argument of the Open Queue event generated preceding.

  • Add iNewRemoteQueueOpenContextHandle to iRemoteQueueOpenContextHandleTable.

  • Set the out-parameter values accordingly:

    • pphContext := iNewRemoteQueueOpenContextHandle.Handle

Additionally, the server SHOULD set the following out-parameter values accordingly:

  • Either to:<27>

    • pdwContext := rOpenQueueDescriptor.Handle

    • phQueue := rOpenQueueDescriptor.Handle

    • dwpQueue := iNewRemoteQueueOpenContextHandle. OpenQueueDescriptorReference

  • Or to:<28>

    • pdwContext := rOpenQueueDescriptor.Handle

    • phQueue := rOpenQueueDescriptor.Handle

    • dwpQueue := rOpenQueueDescriptor.Handle

  • Return MQ_OK (0x00000000).