3.1.4.18 EvtRpcLocalizeExportLog (Opnum 8)

  • Article

The EvtRpcLocalizeExportLog (Opnum 8) method is used by a client to add localized information to a previously created backup event log, because the backup event log does not contain the localized strings for event descriptions. An example of how this can be useful is if a backup event log needs to be copied to other computers so that support personnel on those other computers can access it; if this method has been called, such support personnel can access or view the localized backup event log, which will then contain events with localized strings. Note that a discussion of tools by which administrators or support personnel can work with localized backup event log files in scenarios such as this is out of scope with respect to this protocol specification.

 error_status_t EvtRpcLocalizeExportLog(
   [in, context_handle] PCONTEXT_HANDLE_OPERATION_CONTROL control,
   [in, range(1, MAX_RPC_FILE_PATH_LENGTH), string] 
     LPCWSTR logFilePath,
   [in] LCID locale,
   [in] DWORD flags,
   [out] RpcInfo* error
 );

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

logFilePath: A pointer to a string that contains the path of the backup event log to be localized.

locale: Locale, as specified in [MS-GPSI] Appendix A, to be used for localizing the log.

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

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 nonzero values if the error is related to loading localization information. All nonzero values MUST be treated the same. If the method succeeds, the server MUST set all of the values in the structure to zero.<32>

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success; otherwise, it MUST return an error value as specified in the processing rules in this section.<33> Callers SHOULD treat all return values other than ERROR_SUCCESS equally and not alter their behavior based on any specific error values.

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

In response to this request from the client, the server MUST verify that the logFilePath parameter specifies a valid path to a backup event log. A valid path MUST be a legal file name of the server's file system. The server MUST fail the operation if the logFilePath parameter is invalid with the error ERROR_INVALID_PARAMETER (0x00000057).<34> The server MUST fail the method if the specified backup event log does not exist in the server with the error ERROR_FILE_NOT_FOUND (0x00000002).

Next the server MUST verify that the caller has read access to the log file (specified by the logFilePath parameter) and MUST fail the method if the caller does not have read access with the error 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 3.2.3.4.2. Then the server SHOULD get the security descriptor string from the file system for the log file. Next the server SHOULD perform the read access check using the Access Check algorithm (as specified in [MS-DTYP] section 2.5.3.2).

If the checks above are successful, the server MUST perform the following operations:

  1. The server creates a subdirectory "LocaleMetaData", if the directory does not exist, under the directory where the backup event log file is located (see [PRA-CreateDirectory]). If the directory already exists, the server does nothing. The only expected failures for subdirectory creation are critical system errors, such as file system errors. If the server cannot create the directory, it MUST return the error from the CreateDirectory method that is reporting the error. Otherwise, the server MUST successfully create the subdirectory.

  2. The server creates a file with the name LogFilePath_<Locale>.MTA under the directory LocaleMetaData (see [PRA-CreateFile]). If the file already exists, the server SHOULD always overwrite it. The only expected failures for file creation or overwriting are critical system errors, such as file system errors. If the server can't create the file or overwrite an existing one, it MUST return the error from the CreateFile method that is reporting the error. Otherwise, the server MUST successfully create the file.

  3. The server then opens the backup event log file, reads every event and uses the same internal functionality by which it implements the EvtRpcMessageRender method (section 3.1.4.31) to obtain the localized strings for event levels, keywords, tasks, opcode, and descriptions. The server then saves those localized strings of each event in the newly created file. Note that the EvtRpcMessageRender method needs the PCONTEXT_HANDLE_PUBLISHER_METADATA handle as its first parameter. When the server gets each event, it can get the event publisher name from the event content (see section 2.2.13), thus the server is able to get the context handle by using the internal functionality by which it implements the EvtRpcGetPublisherMetadata method (specified in section 3.1.4.25). The internal functionality by which the server implements EvtRpcGetPublisherMetadata SHOULD use the value of the locale parameter in its processing; the server SHOULD make this value available to that internal functionality by appropriate platform-specific means so that the value can be stored in the publisher metadata object.

    After getting the publisher metadata context handle, the server SHOULD extract the eventId, level, keywords, tasks, and opcode values from the event and fill an EVENT_DESCRIPTOR structure, specified in [MS-DTYP] section 2.3.1. With the context handle and the EVENT_DESCRIPTOR structure, the server can use the internal functionality by which it implements the EvtRpcMessageRender method five times to obtain the localized level, keyword, tasks, opcode, and event description strings. If the server receives an error from the internal functionality by which it implements the EvtRpcMessageRender method, it SHOULD ignore the error and continue processing the next event.

During the preceding 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 whole 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. Any directory or file that has been created SHOULD be deleted. Failure to delete the directory or file SHOULD NOT trigger the server to take any further actions in response.

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

The server SHOULD create a separate file with the name LogFilePath_<Locale>.MTA to hold the localized strings for the events in the log file with the name of LogFilePath. This method does not change anything in the unlocalized, exported log file. Instead, it generates a separate file that contains the localized strings for the events in the exported log file. The user needs to keep both files together when copying them to another computer in order to consume the events with the localized strings. Any protocol method that can access the exported log file will also be able to access the copied exported file. However, correlating the localized strings with the unlocalized event information in the exported log file in a meaningful way for the user is outside of the scope of this protocol. This protocol provides no methods for integrating the localized strings and the exported event log into a single format for presentation.