Export (0) Print
Expand All

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 3.1.4.25) 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
    
    EvtTypeStringArray
        2 (array count)
        Microsoft-Windows-TestProvider/Operational
        Microsoft-Windows-TestProvider/Admin
    
    EvtVarTypeUInt32Array
        2 (array count)
        0
        1
    
    EvtVarTypeUInt32Array
        2 (array count)
        1
        2
    
    EvtVarTypeUInt32Array
        2 (array count)
        0
        0
    
    EvtVarTypeUInt32Array
        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 3.1.4.31) 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 3.1.4.31) 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 3.1.4.33). 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}
    );
    
 
Show:
© 2014 Microsoft