3.1.4.35 EvtRpcRegisterControllableOperation (Opnum 4)

  • Article

The EvtRpcRegisterControllableOperation (Opnum 4) method obtains a CONTEXT_HANDLE_OPERATION_CONTROL handle that can be used to cancel other operations.

 error_status_t EvtRpcRegisterControllableOperation(
   [out, context_handle] PCONTEXT_HANDLE_OPERATION_CONTROL* handle
 );

handle: A context handle for a control object. This parameter MUST be an RPC context handle, as specified in [C706], Context Handles. For information on handle security and authentication considerations, see sections 2.2.20 and 5.1.

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, for a successful operation, the server MUST attempt to create a CONTEXT_HANDLE_OPERATION_CONTROL handle. The server SHOULD create a control object. The control object SHOULD initialize its operation pointer to be NULL and Canceled flag to be FALSE. Then the server SHOULD save the control object pointer in its handle table and return the pointer as the context handle to the client. If it cannot create the handle, the server MUST fail the operation with the error ERROR_OUTOFMEMORY (0x0000000E).

The control handle created with this method can be used by the client when it issues the EvtRpcClearLog (section 3.1.4.16), EvtRpcExportLog (section 3.1.4.17), and EvtRpcLocalizeExportLog (section 3.1.4.18) methods so that the client can cancel those operations if the server takes too long to return. Those methods take the control object as their first parameter, and periodically check the object's Canceled field during the processes. The server SHOULD NOT change the control object's operational pointer data field in its implementation of the EvtRpcClearLog, EvtRpcExportLog, and EvtRpcLocalizeExportLog methods. If the client sets the Canceled field to be TRUE by using the method (section EvtRpcCancel (section 3.1.4.34), the server SHOULD respond to the change by halting the process of clearing, exporting, or localizing the log file.

Note The control object created by this method SHOULD only be used in the EvtRpcClearLog, EvtRpcExportLog, and EvtRpcLocalizeExportLog methods; it is not updated or consumed by any other methods. As specified in sections 3.1.4.8 and 3.1.4.12, operation control objects are created by the server when processing calls to the EvtRpcRegisterRemoteSubscription and EvtRpcRegisterLogQuery methods; those are the only situations in which the server sets the operational pointer data field for the control object. For more information, see sections 3.1.4.8 and 3.1.4.12.

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