A client calls rpc_ACCreateCursorEx to create a cursor for use when peeking and receiving from a message queue.

 HRESULT rpc_ACCreateCursorEx(
   [in] RPC_QUEUE_HANDLE hQueue,
   [in, out] struct CACCreateRemoteCursor* pcc
 );

hQueue:  MUST be an RPC_QUEUE_HANDLE (section 2.2.1.1.2) acquired from the phQueue parameter of rpc_QMOpenQueueInternal (section 3.1.4.17). Prior to this method being invoked, the queue MUST NOT have been deleted, and the queue handle MUST NOT have been closed.

pcc:  A pointer to a CACCreateRemoteCursor (section 2.2.3.4) structure. MUST NOT be NULL.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT,<75> 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: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

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

When processing this call, the server SHOULD:<76>

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

• Locate a LocalQueueContextHandle (section 3.1.1.3) ADM element instance in the server's iLocalQueueContextHandleTable (section 3.1.1.2) where the value of the Handle attribute of the LocalQueueContextHandle ADM element instance equals hQueue.

• If such a LocalQueueContextHandle ADM element instance exists:

  • Declare iLocatedLocalQueueContextHandle and set it to a reference to the located LocalQueueContextHandle ADM element instance.

  • Generate an Open Cursor ([MS-MQDMPR] section 3.1.7.1.1) event with the following argument value:

    • iQueueDesc := iLocatedLocalQueueContextHandle.OpenQueueDescriptorReference.

  • The Open Cursor event returns rCursor, a reference to a Cursor ADM element instance.

  • Set pcc.hCursor to rCursor.Handle.

  • Take no further action and return MQ_OK (0x00000000).

• Else:

  • Locate a RemoteQueueProxyHandle (section 3.1.1.5) ADM element instance in the server's iRemoteQueueProxyHandleTable (section 3.1.1.4) where the value of the Handle attribute of the RemoteQueueProxyHandle ADM element instance equals hQueue.

  • If no such RemoteQueueProxyHandle ADM element instance exists, take no further action and return a failure HRESULT.

  • Declare iLocatedRemoteQueueProxyHandle and set it to a reference to the located RemoteQueueProxyHandle ADM element instance.

  • Bind to the remote server indicated by iLocatedRemoteQueueProxyHandle.PathName and invoke the R_QMCreateRemoteCursor (Opnum 4) (section 3.1.4.4) method. Specify the following parameter values:

    • hQueue := iLocatedRemoteQueueProxyHandle.RemoteContext.

    • The phCursor out-parameter.

  • If the R_QMCreateRemoteCursor (Opnum 4) method fails for any reason, return a failure HRESULT.

  • Declare iNewCursorProxy as a CursorProxy ADM element instance and set its attributes using the following values:

    • Identifier := A new DWORD value unique to iLocatedRemoteQueueProxyHandle.CursorProxyCollection.

    • RemoteCursorHandle := phCursor.

    • IsRemoteCursorHandleInitialized := True.

  • Add iNewCursorProxy to iLocatedRemoteQueueProxyHandle.CursorProxyCollection.

  • Set pcc.hCursor := iNewCursorProxy.Handle.

  • Return MQ_OK (0x00000000).