3.1.4.9 ElfrClearELFW (Opnum 0)

The ElfrClearELFW (Opnum 0) method instructs the server to clear an event log, and, optionally, to back up the event log before the clear operation takes place.

 NTSTATUS ElfrClearELFW(
   [in] IELF_HANDLE LogHandle,
   [in, unique] PRPC_UNICODE_STRING BackupFileName
 );

LogHandle: Handle to the event log to be cleared. This parameter is a server context handle, as specified in section 2.2.6. This handle MUST NOT be one obtained via the ElfrOpenBELA (section 3.1.4.2) method or the ElfrOpenBELW (section 3.1.4.1) method.

BackupFileName: Provides a Unicode string (as specified in section 2.2.11) that points to an NT Object Path of a file in which a current copy of the event log is to be placed. If this is NULL or empty, no backup is to be created. The path is relative to the server rather than the client.

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

In response to this request from the client, the server MUST first check that the handle is valid. The server MUST fail the operation with the error STATUS_INVALID_HANDLE (0xC0000008) if the handle is invalid or if the handle is for a backup event log. Handles to backup event logs are obtained via the ElfrOpenBELW (section 3.1.4.1) method or the ElfrOpenBELA (section 3.1.4.2) method and have the backup flag set.<18>

Note The server determines if a handle is a backup event log handle by looking at the flag for that handle. The handle that is passed in through the LogHandle parameter is a server context handle, which means that the server keeps a data structure for the handle when it is created. If the handle is created for backup purposes, the server puts a backup tag into the data structure. When the handle is passed back to the server, the server locates the handle, and checks the corresponding data structure for that handle to determine if it is a backup handle.<19>

If the BackupFileName is non-NULL and non-empty, the server MUST validate the BackupFileName and fail the call if it is not a valid name. An invalid name is defined as an illegal NT Object Path or a path that specifies a file that already exists. If the BackupFileName is valid, the server MUST attempt to back up the log to the path specified in BackupFileName before the log is cleared. The method MUST fail the operation and not clear the log if the user does not have write access to the location specified by the BackupFileName parameter or if the backup does not succeed for any other reason.<20>

If the BackupFileName is NULL or empty, meaning if the pointer inside the RPC_UNICODE_STRING structure being checked has a size of zero or the buffer inside of BackupFileName is NULL, the method MUST NOT attempt to back up the event log <21> and MUST return a nonzero NTSTATUS value to indicate the failure of the method. The server SHOULD return STATUS_INVALID_PARAMETER (0xC000000D).

If the preceding checks are successful, and if no problems occur during creation of a backup log, the server MUST attempt to clear the associated event log. All events MUST be removed during clearing. Additionally, the state of the log MUST be modified so that the next record written has a record number 1.<22> The server MUST return a value indicating success or failure for this operation. The server MUST return a value indicating success or failure for this operation.