3.1.4.3 RemoteQMOpenQueue (Opnum 2)

The RemoteQMOpenQueue method opens a queue in preparation for subsequent operations against it. This method assumes that the client has called qmcomm:R_QMOpenRemoteQueue to obtain a queue handle; for more information, see [MS-MQMP] section 3.1.4.2. This method is called as part of the sequence of events involved in opening a remote queue by an MQMP application as described in [MS-MQMP] section 4.2. This method MUST be called prior to calling any of the following operations:

• RemoteQMStartReceive

• RemoteQMEndReceive

• RemoteQMCloseQueue

• RemoteQMCloseCursor

• RemoteQMCancelReceive

• RemoteQMPurgeQueue

• RemoteQMStartReceive2

• RemoteQMStartReceiveByLookupId

   HRESULT RemoteQMOpenQueue(
     [in] handle_t hBind,
     [out] PCTX_RRSESSION_HANDLE_TYPE* phContext,
     [in] GUID* pLicGuid,
     [in, range(0, 16)] DWORD dwMQS,
     [in] DWORD hQueue,
     [in] DWORD pQueue,
     [in] DWORD dwpContext
   );
  

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

phContext:  A pointer to a context handle that contains the information about the opened queue, which corresponds to the abstract data model's OpenQueueEntry. The server MUST set this value; it gets deleted on a call to RemoteQMCloseQueue.

pLicGuid: A pointer to a valid GUID ([MS-DTYP] section 2.3.4) that uniquely identifies the client. This value is set to the QueueManager.Identifier ADM element of the queue manager at the client end.

dwMQS: This value MAY be used by the server to impose an implementation-specific limit on the number of concurrent callers.<12>

hQueue: A queue identifier. This value SHOULD be ignored by the server.<13>

pQueue: A DWORD that references an OpenQueueDescriptor of a remote opened queue.

dwpContext: A DWORD that references an OpenQueueDescriptor of a remote opened queue.

Return Values: The method MUST return MQ_OK (0x00000000) on success; otherwise, it MUST return a failure HRESULT, and the client MUST treat all failure HRESULTs identically.

MQ_OK (0x00000000)

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

Exceptions Thrown:

No exceptions are thrown except those thrown by the underlying RPC protocol (see [MS-RPCE]).

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

• Return MQ_ERROR_INVALID_PARAMETER (0xc00e0006) if pLicGuid is NULL or if pQueue or dwpContext is equal to zero.

• The server SHOULD return MQ_ERROR_INVALID_PARAMETER (0xc00e0006) if pQueue is not equal to dwpContext.<14>

• Create a new OpenQueueEntry:

  • The server SHOULD set OpenQueueDescriptorHandle to dwpContext.<15>

  • Set ClientId to the pLicGuid parameter.

• Add the OpenQueueEntry to the rOpenQueueEntryCollection.

• Set phContext to the OpenQueueEntry value, and return MQ_OK (0x00000000).