Share via

3.1.4.34 EvtRpcCancel (Opnum 14)

  • Article

The EvtRpcCancel (Opnum 14) method is used by a client to cancel another method. This can be used to terminate long-running methods gracefully. Methods that can be canceled include the subscription and query functions, and other functions that take a CONTEXT_HANDLE_OPERATION_CONTROL argument. 

 error_status_t EvtRpcCancel(
   [in, context_handle] PCONTEXT_HANDLE_OPERATION_CONTROL handle
 );

handle: A handle obtained by any of the other methods in this interface. This parameter is an RPC context handle, as specified in [C706], Context Handles.

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success; otherwise, it MUST return an implementation-specific nonzero value as specified in [MS-ERREF].

In response to this request from the client, the server MUST first validate the handle. The server SHOULD save the handle value it created in the handle table (as specified in section 3.1.1.12) and compare it with the handle passed here to perform the validation check.<67>

The server MUST return ERROR_INVALID_PARAMETER (0x00000057) if the handle is invalid. For information on handle security and authentication considerations, see sections 2.2.20 and 5.1.

If the above check succeeds, the server MUST attempt to cancel the outstanding call associated with this handle. As specified in section 3.1.1.10, the context handle SHOULD be a control object on the server. The control object contains the detail operation object pointers such as query object pointer, subscription object pointer, and so forth, plus the Boolean flag. The server SHOULD check if the Boolean flag is true. If the flag is true, the server does nothing and returns success. If this flag is not true, the server SHOULD get the operation object pointer and cancel the operation by stopping operation object processing. That would include stopping processing of the query or subscription tasks and then setting its cancelation Boolean flag to true. For information, see section 3.1.4.

In response to this call, the server MUST NOT remove the associated handle from its handle table.

If the server is too busy to process the outstanding operation, it might not be able to cancel the call. The server SHOULD then return ERROR_CANCELLED (0x00004C7) or other implementation-dependent error codes. If there is no outstanding call or operation, or if the outstanding call or operation has already been canceled, the server SHOULD return ERROR_SUCCESS (0x00000000).

The server MUST return a value indicating success or failure for this operation.