Share via

3.1.4.5 R_CloseCursor (Opnum 5)

  • Article

The R_CloseCursor method closes the handle for a previously created cursor. The client MUST call this method to reclaim resources on the server allocated by the R_CreateCursor (Opnum 4) (section 3.1.4.4) method.

 HRESULT R_CloseCursor(
   [in] handle_t hBind,
   [in] QUEUE_CONTEXT_HANDLE_NOSERIALIZE phContext,
   [in] DWORD hCursor
 );

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 the cursor was associated in a call to the R_CreateCursor method. 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.

hCursor: MUST be set by the client to the handle of the cursor to be closed. The handle MUST have been obtained by a prior call to the R_CreateCursor method and MUST NOT have been closed through a prior call to the R_CloseCursor method.

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

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

Exceptions Thrown:

No exceptions are thrown except those that are 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 fOpenQueueDescriptor by comparing the phContext parameter with the Handle ADM attribute for all OpenQueueDescriptor ADM element instances maintained by the local QueueManager ADM element instance.

  • If fOpenQueueDescriptor is found, then find the corresponding Cursor ADM element instance fCursor by comparing the hCursor parameter with the Handle ADM attribute of each Cursor ADM element instance in fOpenQueueDescriptor.CursorCollection.

  • If not found, return a failure HRESULT.

  • Generate a Close Cursor ([MS-MQDMPR] section 3.1.7.1.2) event with the following input:

    • iCursor :=  fCursor

  • Return MQ_OK (0x00000000).