3.1.4.15 EvtRpcGetLogFileInfo (Opnum 18)

The EvtRpcGetLogFileInfo (Opnum 18) method is used by a client to get information about a live channel or a backup event log.

 error_status_t EvtRpcGetLogFileInfo(
   [in, context_handle] PCONTEXT_HANDLE_LOG_HANDLE logHandle,
   [in] DWORD propertyId,
   [in, range(0, MAX_RPC_PROPERTY_BUFFER_SIZE)] 
     DWORD propertyValueBufferSize,
   [out, size_is(propertyValueBufferSize)] 
     BYTE* propertyValueBuffer,
   [out] DWORD* propertyValueBufferLength
 );

logHandle: A handle to an event log. This parameter is an RPC context handle, as specified in [C706], Context Handles. For more information about the server-side object that maps to this handle, see section 3.1.4.19.

propertyId: A 32-bit unsigned integer that indicates what log file property (as specified in section 3.1.1.6) needs to be retrieved.

Value	Meaning
EvtLogCreationTime 0x00000000	A FILETIME containing the creation time of the file. This is the creation time of a log file associated with the channel or the creation time of the backup event log file in the server's file system.
EvtLogLastAccessTime 0x00000001	A FILETIME containing the last access time of the file. This is the last access time of a log file associated with the channel or the last access time of the backup event log file in the server's file system.
EvtLogLastWriteTime 0x00000002	A FILETIME containing the last write time of the file. This is the last written time of a log file associated with the channel or the last written time of the backup event log file in the server's file system.
EvtLogFileSize 0x00000003	An unsigned 64-bit integer containing the size of the file. This is the file size of a log file associated with the channel or the file size of the backup event log file in the server's file system.
EvtLogAttributes 0x00000004	An unsigned 32-bit integer containing the attributes of the file. The attributes are implementation-specific, and clients MUST<23> treat all values equally. The attributes are tracked by the server's file system and SHOULD be able to be retrieved from the file system.
EvtLogNumberOfLogRecords 0x00000005	An unsigned 64-bit integer containing the number of records in the file. See the following processing rules for how the server gets this value.
EvtLogOldestRecordNumber 0x00000006	An unsigned 64-bit integer containing the oldest record number in the file. See the following processing rules for how the server gets this value.
EvtLogFull 0x00000007	A BOOLEAN value; MUST be true if the log is full, and MUST be false otherwise. See the following processing rules for how the server gets this value.

propertyValueBufferSize: A 32-bit unsigned integer that contains the length of caller's buffer in bytes.

propertyValueBuffer: A byte-array that contains the buffer for returned data.

propertyValueBufferLength: A pointer to a 32-bit unsigned integer that contains the size in bytes of the returned data.

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success. The method MUST return ERROR_INSUFFICIENT_BUFFER (0x0000007A) if the buffer is too small; otherwise, it MUST return a different 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 log handle value it creates in the EvtRpcOpenLogHandle (section 3.1.4.19) method in its handle table (as specified in section 3.1.1.12) so that it can compare that value with the value in the logHandle parameter to perform the check. If the values differ, the handle is invalid.<24> The server MUST fail the operation if the handle is invalid with the error code ERROR_INVALID_PARAMETER (0x00000057).

Next, the server MUST verify the propertyId value as one specified in the preceding propertyId's fields table. Otherwise, it SHOULD return ERROR_INVALID_PARAMETER (0x00000057).

If propertyValueBufferSize is too small, the server MUST return the size needed in the propertyValueBufferLength parameter and fail the method with a return code of ERROR_INSUFFICIENT_BUFFER (0X0000007A).

If the preceding checks succeed, the server MUST attempt to return the request information. The server SHOULD first cast the logHandle into the log object. The server SHOULD decide if the Channel pointer points to a live channel or the handle to a backup event log file based on the LogType field. If it is a live channel, the server SHOULD get the associated log file path and open the file to get a file handle. If it is a backup event log file, the log object contains the handle to the file. Then the server SHOULD get the EvtLogCreationTime, EvtLogLastAccessTime, EvtLogLastWriteTime, EvtLogFileSize, and EvtLogAttributes information by querying the file system to get the creation time, last access time, last written time, file size, and file attributes of the specified log file (if channel is specified, the log file is the disk file which associates with the channel).

Note This information is tracked by the file system automatically and the server does not need to touch any files for any operation, such as exporting events from the channel or clearing events in a channel.

The server keeps the number of event records, the oldest event record, and the log full flag in its live channel file (log file associated with the channel) or backup event log file header (as specified in section 3.1.1.6). The server reads the information directly when returning the mentioned properties to the client.

The server MUST pack the return data into a single BinXmlVariant structure, as specified in section 2.2.18, and copy it into the buffer that is pointed to by the propertyValueBuffer parameter. The server MUST NOT update its state.

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