Share via

3.1.4.31 EvtRpcMessageRender (Opnum 9)

  • Article

The EvtRpcMessageRender (Opnum 9) method is used by a client to get localized descriptive strings for an event.

 error_status_t EvtRpcMessageRender(
   [in, context_handle] PCONTEXT_HANDLE_PUBLISHER_METADATA pubCfgObj,
   [in, range(1, MAX_RPC_EVENT_ID_SIZE)] 
     DWORD sizeEventId,
   [in, size_is(sizeEventId)] BYTE* eventId,
   [in] DWORD messageId,
   [in] EvtRpcVariantList* values,
   [in] DWORD flags,
   [in] DWORD maxSizeString,
   [out] DWORD* actualSizeString,
   [out] DWORD* neededSizeString,
   [out, size_is(,*actualSizeString), range(0, MAX_RPC_RENDERED_STRING_SIZE)] 
     BYTE** string,
   [out] RpcInfo* error
 );

pubCfgObj: A handle to a publisher object. This parameter is an RPC context handle, as specified in [C706], Context Handles. This value comes from the return parameter pubMetadata of the function EvtRpcGetPublisherMetadata (section 3.1.4.25).

sizeEventId: A 32-bit unsigned integer that contains the size, in bytes, of the data in the eventId field. The server MUST ignore this value if EvtFormatMessageId is specified as the flags parameter. If EvtFormatMessageId is not specified in the flags parameter, the server MUST use the sizeEventId parameter and ignore the messageId parameter.

eventId: A pointer to an EVENT_DESCRIPTOR structure, as specified in [MS-DTYP] section 2.3.1.

messageId: A 32-bit unsigned integer that specifies the required message. This is an alternative to using the eventID parameter used by a client application that has obtained the value through some method outside those documented by this protocol. The server MUST ignore this value unless the flags value is set to EvtFormatMessageId; in which case, the server MUST use this value to determine the required message and ignore the eventID parameter.

values: An array of strings used as substitution values for event description strings. The number of strings submitted is determined by the number of description strings contained in the event message specified by the eventID or messageId parameter.<62>

flags: For all options except EvtFormatMessageId, the eventId parameter is used to specify an event descriptor. For the EvtFormatMessageId option, the messageId is used for locating the message. This MUST be set to one of the values in the following table, which indicates the action a server is requested to perform.

Value

Meaning

EvtFormatMessageEvent

0x00000001

Locate the message for the event that corresponds to eventID, and then insert the values specified by the values parameter.

EvtFormatMessageLevel

0x00000002

Extract the level field from eventID, and then return the localized name for that level.

EvtFormatMessageTask

0x00000003

Extract the task field from eventID, and then return the localized name for that task.

EvtFormatMessageOpcode

0x00000004

Extract the opcode field from eventID, and then return the localized name for that opcode.

EvtFormatMessageKeyword

0x00000005

Extract the keyword field from eventID, and then return the localized name for that keyword.

EvtFormatMessageChannel

0x00000006

Extract the channel field from eventID, and then return the localized name for that channel.

EvtFormatMessageProvider

0x00000007

Return the localized name of the publisher.

EvtFormatMessageId

0x00000008

Locate the message for the event corresponding to the messageId parameter, and then insert the values specified by the values parameter.

maxSizeString: A 32-bit unsigned integer that contains the size, in bytes, of the string that is provided by the caller.

actualSizeString: A pointer to a 32-bit unsigned integer that, on return, contains the actual size, in bytes, of the resulting description (including null termination).

neededSizeString: A pointer to a 32-bit unsigned integer that, on return, contains the needed size, in bytes (including null termination).

string: A pointer to a bytearray that, on return, contains a localized string containing the message requested. This can contain a simple string, such as the localized name of a keyword, or a fully rendered message that contains multiple inserts.

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 the necessary resource. All nonzero values MUST be treated the same. If the method succeeds, the server MUST set all the fields in the structure to 0.

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success. The method MUST return ERROR_INSUFFICIENT_BUFFER (0x0000007A) if maxSizeString is too small to hold the result string. In that case, neededSizeString MUST be set to the necessary size. Otherwise, the method 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 context handle value it creates in the EvtRpcGetPublisherList method (as specified in section 3.1.4.25) in its handle table (as specified in 3.1.1.12) and compare it with the handle passed here to perform the handle validation work.<63> The server MUST return ERROR_INVALID_PARAMETER (0x00000057) if the handle is invalid or there is no such handle on the server.

The server MUST then check the flags parameter. If flags is not one of the 8 values in the flags table in this section, the server MUST fail the method with the error ERROR_INAVLID_PARAMETER(0x00000057).

The server MUST ignore the eventId parameter if EvtFormatMessageId is specified as the flags parameter. If EvtFormatMessageId is not specified in the flags parameter, the server MUST use eventId parameter and ignore the messageId parameter.

If validation is successful, the server SHOULD cast the pubCfgObj context handle into the publisher metadata object. The publisher metadata object contains the ResourceFileHandle which the server SHOULD use to read the publisher resource information (as specified in section 3.1.1.14) to serve this method. The server MUST attempt to return a localized string. If the string being requested is for the level, task, opcode, and keyword choices, the server MUST use its own localized string table if the value is within the range of the server (the value is retrieved from the eventId parameter). The server MUST define range values as the following:

  • Levels 0 through 15

  • Task 0

  • Opcodes 0 through 9, and 240

  • The following keywords for levels 0 through 15.

    • 0

    • 0x1000000000000

    • 0x2000000000000

    • 0x4000000000000

    • 0x8000000000000

    • 0x10000000000000

    • 0x20000000000000

    • 0x40000000000000

    • 0x80000000000000.

For example, if the level requested is 2, the server's list of strings for levels MUST be used since 2 is in the range [0,15]. The server MUST NOT change any state.

The server MUST prepare the description strings for these defined values itself. There are no formal recommendations about what strings to assign for these reserved values. The server can assign any strings for the keywords for the levels 0 through 15 values or it can assign part of them for its own development purpose and leave the remaining as dummy strings. The assigned strings MUST be kept by the server in dedicated files. The dedicated files which keep the predefined strings are the server's own localized string tables. Thus the server can be a default publisher. It maintains these predefined strings for every language. The server can then have multiple language-specific resource files and each language-specific resource file contains all the predefined strings for one language. For more information on language-specific resource files, see [MSDN-MUIResrcMgmt].

When the EvtFormatMessageId is specified in the flags parameter, the server SHOULD use the messageId parameter and search through the language-specific resource file (as specified in section 3.1.1.13) to find the messageId that the client specified. Once the server locates the messageId in the language-specific resource file, it gets the localized string associated with that messageId and returns the result to the client.<64>

When the EvtFormatMessageId is not specified in the flags parameter, the server SHOULD first use the eventId parameter to find the messageId in the publisher resource file. Depending on the flags value, processing is as follows:

  • If EvtFormatMessageEvent is specified in the flags parameter, the server SHOULD search the events information (as specified in section 3.1.1.14) in the publisher resource file to get the messageId for that event and then get the event description string from the language-specific resource file using the messageId.

  • If EvtFormatMessageLevel, EvtFormatMessageTask, EvtFormatMessageOpcode, or EvtFormatMessageKeyword is specified in the flags parameter, the server SHOULD first get the event information based on the eventId and then locate the level messageId, task messageId, opcode messageId, or the keyword messageId for that event based on the flags value. Next, it uses the messageId to get the description string from the language-specific resource file.

  • If EvtFormatMessageProvider is specified in the flags parameter, the server SHOULD first get the events information (as specified in section 3.1.1.14) based on the eventId. Next, it SHOULD search the publisher information (as specified in the section 3.1.1.14) in the publisher resource file to get the messageId for that publisher name based on the publisher identifier it gets from the first step and then get the publisher name string from the language-specific resource file using the messageId.

  • If EvtFormatMessageChannel is specified in the flags parameter, the server SHOULD first get the events information (as specified in section 3.1.1.14) based on the eventId. Next, it SHOULD search the channel information (as specified in section 3.1.1.14) in the publisher resource file to get the messageId parameter for that channel name based on the publisher identifier it gets from the first step and then get the localized channel name string from the language-specific resource file using the messageId parameter.

The message string that the server gets is from the publisher localized string table on the server. Because the publisher object contains the locale value that the client requires when opening the publisher through the EvtRpcGetPublisherMetadata function, the server determines which localized string table (as specified in section 3.1.1.13) is needed to fetch the localized string.

If the server can't find the localized string either because it can't find the corresponding messageId or the localized string is missing for the messageId, it SHOULD fail the method with the error code ERROR_EVT_MESSAGE_ID_NOT_FOUND (0x00003AB4) or ERROR_EVT_MESSAGE_NOT_FOUND (0x00003AB3).

The message strings that the server gets from the language-specific resource file can contain some "%" symbols, which are symbol indicators of substitutions. If the client specifies the values parameter, which is an array of string values, those values will replace the "%" symbols in the message string. For example, the following could be a raw message string:

  • "The file system has failed to locate the file %1 with the error %2." And if the values contain 2 elements, one is "sample.evtx", the other is "access denied". Then the string will be expanded into "The file system has failed to locate the file sample.evtx with the error access denied". If the values array contains more elements than the required substitution, the server SHOULD discard the extra ones. If the values array contains less elements than the required substitution, the server SHOULD replace with as many as possible and leave the left one as %number for the final result string. The server SHOULD NOT fail the method regardless of what is specified for the values parameter.

By checking the flags parameter, the server knows which information (level, task, opcode, keywords, and so on) the client requests. The server MUST fail the method with the error ERROR_INVALID_PARAMETER(0x00000057) if the flags parameter is not one of the values specified in this section.

When EvtFormatMessageId is specified in the flags parameter, the server SHOULD use the messageId parameter and search through the publisher resource file to find the messageId the client specified. Once the server locates the messageId in the publisher resource file, it will get the localized string associated with that messageId and return the result to the client.<65>

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