Share via

3.1.4.16 EvtRpcClearLog (Opnum 6)

  • Article

The EvtRpcClearLog (Opnum 6) method instructs the server to clear all the events in a live channel, and optionally, to create a backup event log before the clear takes place.

 error_status_t EvtRpcClearLog(
   [in, context_handle] PCONTEXT_HANDLE_OPERATION_CONTROL control,
   [in, range(0, MAX_RPC_CHANNEL_NAME_LENGTH), string] 
     LPCWSTR channelPath,
   [in, unique, range(0, MAX_RPC_FILE_PATH_LENGTH), string] 
     LPCWSTR backupPath,
   [in] DWORD flags,
   [out] RpcInfo* error
 );

control: A handle to an operation control object. This parameter is an RPC context handle, as specified in [C706], Context Handles.

channelPath:  A pointer to a string that contains the path of the channel to be cleared.

backupPath: A pointer to a string that contains the path of the file in which events are to be saved before the clear is performed. A value of NULL indicates that no backup event log is to be created (the events to be cleared are not to be saved).

flags: A 32-bit unsigned integer that MUST be set to zero when sent and MAY be ignored on receipt.<25>

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

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

The server does not validate the control handle passed to EvtRpcClearLog and it SHOULD assume that this parameter is always valid when the method is invoked.

The server MUST verify that the channelPath parameter specifies a correct channel name by looking up the channel name in its channel table. The server SHOULD fail the call if the channelPath parameter is not an entry in its channel table with the error code ERROR_EVT_CHANNEL_NOT_FOUND (0x00003A9F).

If the backupPath parameter is non-NULL and non-empty, the server MUST validate the path and fail the call if it is not a file path (an illegal file path for the server's file system) or if it specifies a file that already exists. If the path is an illegal file path, the server SHOULD return the error ERROR_INVALID_PARAMETER (0x00000057). If the path specifies a file which exists on the server, the server SHOULD return the error ERROR_FILE_EXISTS (0x00000050).

Next, the server MUST verify if the client has write and clear access to the channel and write access to the backup file if specified. To perform the access check, the server SHOULD first determine the identity of the caller. Information determining the identity of the caller for the purpose of performing an access check is specified in [MS-RPCE] section 3.2.3.4.2. Then, if the client specifies a channel, the server SHOULD read the channel's access property (as specified in section 3.1.4.21) as the security descriptor string. Next, the server SHOULD be able to perform the write and clear access check using the Access Check algorithm (as specified in [MS-DTYP] section 2.5.3.2). The server MUST fail the method with the error ERROR_ACCESS_DENIED (0x00000005) if the client does not have write and clear access to the channel.

If the client specifies the backupPath, the server SHOULD first impersonate the identity of the caller. For information on how to impersonate the client's identity for the purpose of performing an authorization or security check, see [MS-RPCE] (section 3.3.3.4.3). Then the server SHOULD call the file system component to attempt to create the backup file. Once the server impersonates the client's identity, it can determine whether the client has write access because the file creation will fail with ERROR_ACCESS_DENIED (0x00000005) if the client does not have write access. If the server fails to create the backup file, it MUST return the error (a nonzero value as specified in [MS-ERREF]) reported by the underlying file system component.<27> Otherwise, the server MUST successfully create the backup file.

If the backupPath parameter is valid, the server MUST attempt to back up the log to the path specified in the backupPath parameter before the log is cleared. The method MUST fail and not clear the log if the backup does not succeed with any possible implementation-based error code.

If the backupPath parameter is NULL or empty, the method MUST NOT attempt to back up the event log but SHOULD still clear the events in the channel.

If the previous checks are successful and if there are no problems in creating a backup log, the server MUST attempt to clear the associated event log. All events MUST be removed during clearing. During this process, the server SHOULD check the Canceled field of the operation control object in the control parameter periodically, for example, once every 100 milliseconds. If the Canceled field becomes TRUE and the clearing operation has not been finished, the server SHOULD abandon the current operation and return to the client immediately with the error code ERROR_CANCELLED (0x000004C7) without updating any state. On a successful return, the server SHOULD reset the numberOfRecords to 0 and isLogFull to false for the header of its associated log file for the channel. The server does not need to update the curPhysicalRecordNumber and oldestEventRecordNumber. The LogCreationTime, LogLastAccessTime, LogLastWriteTime, LogFileSize, and LogAttributes attributes of the associated log file for the channel are tracked by the server's file system.

If all events are successfully deleted ("cleared"), the server MUST return ERROR_SUCCESS to indicate success. This method SHOULD only fail in extreme conditions, such as lack of system resources, file system error, or hardware error, and such issues are not part of the processing for the EventLog Remoting Protocol Version 6.0. In these cases, the method MUST return an implementation-specific error, as specified in [MS-ERREF], from lower level components unchanged. Depending on the server's implementation detail, the protocol has no specific error return recommendation other than it MUST come from [MS-ERREF].

Note The server does not need to update any state or information for the created backup event log file.