4.9 Render Localized Event Message Example

In this example, the client asks to get the event description from a known publisher. This involves the following steps:

  1. The client registers with RPC to obtain an RPC binding handle to the service based on the endpoint information specified in section 2.1. For information on how to get the RPC binding handle, see [MSDN-BNDHNDLS].

  2. The client calls the EvtRpcGetPublisherMetadata method (section to open the publisher metadata context handle.

     error_status_t EvtRpcGetPublisherMetadata(
       [in] RPC_BINDING_HANDLE binding = {binding handle from step 1.},
       [in, unique, range(0, MAX_RPC_PUBLISHER_ID_LENGTH), string] 
         LPCWSTR publisherId = "Microsoft-Windows-TestProvider",
       [in, unique, range(0, MAX_RPC_FILE_PATH_LENGTH), string] LPCWSTR logFilePath = NULL,
       [in] LCID locale = 1033,
       [in] DWORD flags = 0,
       [out] EvtRpcVariantList* pubMetadataProps,
       [out, context_handle] PCONTEXT_HANDLE_PUBLISHER_METADATA* pubMetadata
  3. In the response to the client call, the server finds the registered publisher "Microsoft-Windows-TestProvider" and opens its resource file. The server then creates a publisher metadata object, which contains the publisher name "Microsoft-Windows-TestProvider", the resource file location such as "c:\windows\system32\TestProvider.dll", the opened file handle, and the locale value 1033. The server then casts the object into the publisher metadata context handle.

    At the same time, the server reads the publisher resource file and extracts some of the publisher metadata and saves them in the pubMetadataProps parameter. Suppose this test publisher declares two channels: "Microsoft-Windows-TestProvider/Operational" and "Microsoft-Windows-TestProvider/Admin". The publisher message file and parameter file are the same file as the resource file (a publisher usually uses the same file for all the resource, message, and parameter files). Then the data in pubMetadataProps will look as follows:

     EvtCarTypeGuid   {836e133c-493c-4885-a780-4f0c61430fb9}
     EvtVarTypeString  c:\windows\system32\TestProvider.dll
     EvtVarTypeString  c:\windows\system32\TestProvider.dll
     EvtVarTypeString  c:\windows\system32\Testrovider.dll
         2 (array count)
         2 (array count)
         2 (array count)
         2 (array count)
         2 (array count)
         1001 (message Id for the channel)
         1002 (message Id for the channel)
  4. After the client gets the publisher metadata context handle, it calls the EvtRpcMessageRender method (section to render the desired event description.

     error_status_t EvtRpcMessageRender(
       [in, context_handle] PCONTEXT_HANDLE_PUBLISHER_METADATA pubCfgObj = {handlefrom step 2},
       [in, range(1, MAX_RPC_EVENT_ID_SIZE)] DWORD sizeEventId = sizeof(EVENT_DESCRIPTOR),
       [in, size_is(sizeEventId)] BYTE* eventId = {pointer to the event descriptor for an event},
       [in] DWORD messageId = 0,
       [in] EvtRpcVariantList* values = {pointer to values which will be used for substituion},
       [in] DWORD flags = 0x00000001 ({Format the event),
       [in] DWORD maxSizeString = 1024,
       [out] DWORD* actualSizeString,
       [out] DWORD* neededSizeString,
       [out, size_is(,*actualSizeString), range(0, MAX_RPC_RENDERED_STRING_SIZE)] BYTE** string,
       [out] RpcInfo* error

    For the eventId parameter in this example, the values can look as follows:

     0x0010   --- EventId
      0x02       --- Level
      0x00       --- Channel
      0x20       --- OpCode
      0x1000     --- Task
      0x8000000000000000 --- Keyword
  5. In response to the client call, the server finds the event according to the passing event descriptor and reads out the raw event description strings from the provider publisher resource file. Because in step 2, the client requests the locale value as 1033, the server opens the English publisher resource file. Suppose the raw event description is "The system has been restarted after applying the updates of %1". The server then reads the data from the values provided by the client (assume it is "Adobe Flash") and replaces the %1 with the value it reads out. Thus, the returned string is:

     "The system has been restarted after applying the updates of Adobe Flash".

  6. Later, if the client needs to get the localized message for the event level, it calls the same EvtRpcMessageRender method (section with the same parameters except the flags value is 0x00000002.

  7. In response to the client call, the server finds the event according to the passing event descriptor and reads out the level value. The level is 2, which means it falls into the system defined category. Suppose the system defined string for a level with the value 2 is "Error" for English. Thus, the resulting string is "Error".

  8. When the client is done, it closes the publisher metadata handle by calling EvtRpcClose (section In this call, the server frees all resources related to the publisher and closes the resource file.

     error_status_t EvtRpcClose(
        [in, out, context_handle] void** handle = {publisher metadata handle}