The R_CreateCursor method creates a cursor and returns a handle to it. The handle can be used in subsequent calls to the R_StartReceive (Opnum 7) (section 3.1.4.7) method or the R_StartTransactionalReceive (Opnum 13) (section 3.1.4.13) method to specify a relative location in the queue from which to receive a message.

 HRESULT R_CreateCursor(
   [in] handle_t hBind,
   [in] QUEUE_CONTEXT_HANDLE_NOSERIALIZE phContext,
   [out] DWORD* phCursor
 );

hBind: MUST specify an RPC binding handle parameter, as specified in [MS-RPCE] section 2.

phContext: MUST be set by the client to the QUEUE_CONTEXT_HANDLE_NOSERIALIZE (section 2.2.4.1) handle with which to associate the cursor. The handle MUST have been returned by the server in the pphQueue output parameter of a prior call to the R_OpenQueue (Opnum 2) (section 3.1.4.2) method and MUST NOT have been closed through a prior call to the R_CloseQueue (Opnum 3) (section 3.1.4.3) method. This value MUST NOT be NULL.

phCursor: MUST be set by the server to a handle for the created cursor.

Return Values: On success, this method MUST return MQ_OK (0x00000000).

If an error occurs, the server MUST return a failure, and the client MUST treat all failure HRESULTs identically.

The client MUST disregard all out-parameter values when any failure HRESULT is returned.

Exceptions Thrown:

No exceptions are thrown except those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

When processing this call, the server MUST:

• Find the corresponding OpenQueueDescriptor ADM element instance by comparing the pphContext parameter with the Handle ADM attribute for all OpenQueueDescriptor ADM element instances maintained by the local QueueManager ADM element instance.

• If not found, return a failure HRESULT.

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

  • iQueueDesc := The found OpenQueueDescriptor ADM element instance.

• Set the phCursor parameter to rCursor.Handle.

• Return MQ_OK (0x00000000).