18.104.22.168 EvtRpcExportLog (Opnum 7)
The EvtRpcExportLog (Opnum 7) method instructs the server to create a backup event log at a specified file name.
error_status_t EvtRpcExportLog( [in, context_handle] PCONTEXT_HANDLE_OPERATION_CONTROL control, [in, unique, range(0, MAX_RPC_CHANNEL_NAME_LENGTH), string] LPCWSTR channelPath, [in, range(1, MAX_RPC_QUERY_LENGTH), string] LPCWSTR query, [in, range(1, MAX_RPC_FILE_PATH_LENGTH), string] LPCWSTR backupPath, [in] DWORD flags, [out] RpcInfo* error );
channelPath: A pointer to a string that contains the channel name (for a live event log) or file path (for an existing backup event log) to be used to create a backup event log.
query: A pointer to a string that contains a query that specifies events to be included in the backup event log.
backupPath: A pointer to a string that contains the path of the file for the backup event logs to be created.
flags: The client MUST set the flags parameter to one of the following values.
Channel parameter specifies a channel name.
Channel parameter specifies a file name.
In addition, the client MAY set the following value in the flags parameter:
The query MUST succeed even if not all the channels or backup event logs that are specified in the query are present, or if the channelPath parameter specifies channels that do not exist.
The server MAY ignore unrecognized flag combinations.<25>
error: A pointer to an RpcInfo (section 2.2.1) structure in which to place error information in the case of a failure. The RpcInfo (section 2.2.1) structure fields MUST be set to a nonzero value if the error is related to parsing the query. In addition, the server MAY set the suberror fields to nonzero values for other types of errors. All nonzero values MUST be treated the same. If the method succeeds, the server MUST set all of the values in the structure to 0.
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].
The server does not validate the control handle passed to EvtRpcExportLog, and it SHOULD assume that this parameter is always valid when the method is invoked.
In response to this request from the client, if the flags parameter contains the value 0x00000001 (flags & 0x00000001 != 0), the server MUST interpret the channel parameter as a channel name. The server then SHOULD search its channel table to find the corresponding entry which has the same channel name. If the server can't find the entry, the specified channel name is invalid and the server SHOULD return ERROR_EVT_CHANNEL_NOT_FOUND (0x00003A9F). If the flags parameter contains the value 0x00000002 (flags & 0x00000002 != 0), the server MUST interpret channel as an existing backup event log file name. The server SHOULD then check if the specified file exists on the server. If the file does not exist, the file path is invalid and the server SHOULD return ERROR_FILE_NOT_FOUND (0x00000002).
The server SHOULD validate that the flags contain one and only one of EvtQueryChannelPath and EvtQueryFilePath; and that no flags which are not defined above are specified. The server SHOULD return error code ERROR_INVALID_PARAMTER (0x00000057) if the flag validation fails.<26>
The server MUST verify that the query parameter is a valid XPath expression with correct syntax, based on the grammar definition provided in section 2.2.15 and if it is not, fail the operation with the error code ERROR_INVALID_PARAMETER (0x00000057). For information on XPath filters supported by this protocol, see section 2.2.15.
The server MUST verify that backupPath is a valid path (a legal file name for the server's file system), and fail the method if it is not valid or if it specifies a file that already exists. The server SHOULD return ERROR_INVALID_PARAMETER (0x00000057) if the path is invalid or ERROR_FILE_EXISTS (0x00000050) if the specified file already exists on the server.
Next, the server MUST verify that the caller has read access to the channel or the backup event log file and MUST fail the method if the caller does not have read access with the error code ERROR_ACCESS_DENIED (0x00000005). 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 22.214.171.124.2. Then, if the client specifies a channel, the server SHOULD read the channel's access property (as specified in section 126.96.36.199) 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 188.8.131.52).
During the exporting log 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 exporting 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. If the server has created a new backup file and the operation has been canceled, the created file SHOULD be deleted. Failure to delete the file SHOULD NOT trigger the server to take any further actions in response.
If the checks above are successful, the server MUST attempt to create a new backup event log that contains only the records selected by the filter specified by the query parameter. The server SHOULD first impersonate the identity of the client. For information on how to impersonate the client's identity for the purpose of performing an authorization or security check, see [MS-RPCE] (section 184.108.40.206.3). Then the server SHOULD call the file system component to create a new backup event log 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 new backup event log 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 file. There is no server state that needs to be updated by this method. However, the server SHOULD ensure the LogNumberOfRecords, LogOldestRecordNumber, and LogFull properties of the created backup log are the correct value. If the query parameter is NULL, the created backup event log file SHOULD be the copy of the event log file associated with the live channel so that the LogNumberOfRecords, LogOldestRecordNumber, and LogFull properties are kept in the backup event log file and consequently have the same values as in the event log file associated with the live channel.
If the query parameter is not NULL, the server SHOULD then read each event from the log file associated with the live channel and determine whether it meets the criteria specified by the query parameter. For every event that passes the filter given in the query parameter, the server SHOULD write it to the created backup file. The event record number of the first event that is written into the created backup file SHOULD be the value of LogOldestRecordNumber. The LogNumberOfRecords property SHOULD be set to the number of total events the server writes to the backup file. The server SHOULD set the isLogFull property to be FALSE and SHOULD set the curPhysicalRecordNumber property to the value of (LogNumberOfRecords - 1).
The created backup file SHOULD be treated as read-only and never modified subsequently.
The LogCreationTime, LogLastAccessTime, LogLastWriteTime, LogFileSize, and LogAttributes attributes of the created backup event log file are tracked by the server's file system. The LogNumberOfRecords, LogOldestRecordNumber, and LogFull attributes are tracked by numberOfRecords, oldestRecordNumber, and isLogFull in the backup event log file header.
The server MUST return a value indicating success or failure for this operation.
Note The exported backup event log file does not contain the localized event description strings because the localized strings would consume considerable storage space if included in the exported log file. If the backup log is consumed on the same machine where it is created or on other machines where the publisher is registered, the strings can be retrieved from the publisher on demand. Localized event description strings only need to be added to an exported backup event log file when that file is moved to a different machine where the publisher is not registered. Localized event description strings can be added to an exported backup event log file by calling the EvtRpcLocalizeExportLog (section 220.127.116.11) method.