Share via

3.1.5.4 rpc_ACCreateCursorEx (Opnum 3)

  • Article

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