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:
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).