4.12 Get Event Metadata Example
In this example, the client retrieves the event metadata information from a known publisher on the server.
This involves the following steps:
The client registers with RPS to obtain an RPC binding handle to the service based on the endpoint information specified in section 2.1. For information about how to obtain an RPC binding handle, see [MSDN-BNDHNDLS].
The client calls the EvtRpcGetPublisherMetadata method (section 3.1.4.25) to obtain a publisher metadata context handler.
error_status_t EvtRpcGetPublisherMetadata( [in] RPC_BINDING_HANDLE binding = {handle from step 1}, [in, unique, range(0, MAX_RPC_PUBLISHER_ID_LENGTH), string] LPCWSTR publisherId = L"Microsoft-Windows-SamplePublisher", [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 );The server then opens the publisher resource file for the publisher whose name is "Microsoft-Windows-SamplePublisher" and creates a publisher metadata object. In this example, the publisher's resource file is %SystemDrive%\windows\SamplePublisher.dll; thus, the server sets the values for the data fields in the publisher metadata object as follows:
HandleType: 4. Indicates the publisher metadata type.
ResourceFile: %SystemDrive%\windows\SamplePublisher.dll.
MessageFile: %SystemDrive%\windows\SamplePublisher.dll.
ParameterFile: %SystemDrive\windows\SamplePublisher.dll.
Locale: 1033.
ResourceFileHandle: 0x00000AF0. Indicates the handle for the resource file.
The server also fills the pubMetadataProps parameter with an EvtRpcVariantList containing 29 EvtRpcVariants as specified in section 3.1.4.25. The server obtains the data for these EvtRpcVariants from two sources, its publisher table and the publisher resource file. The server locates the publisher entry in its publisher table based on the specified publisherId parameter from the client. The server reads the publisherGUID, ResourceFilePath, ParameterFilePath, MessageFilePath, ChannelReferenceIndex, ChannelReferenceID, and ChannelReferenceFlags values directly from the publisher entry in the publisher table. The server locates the channel information in the publisher resource file in order to obtain the channel name strings and channel message IDs, which correspond to the ChannelReferencePath and ChannelReferenceMessageID entries of the pubMetadataProps list. In this example, the data is as follows:
[0] 15 ---- EvtVarTypeGuid {59206ea5-6655-4ffa-8426-a2ce213b26f5} ---- The publisher GUID [1] 1 ---- EvtVarTypeString "%SystemDrive%\windows\SamplePublisher.dll" [2] 1 ---- EvtVarTypeString "%SystemDrive%\windows\SamplePublisher.dll" [3] 1 ---- EvtVarTypeString "%SystemDrive%\windows\SamplePublisher.dll" [4] 0 ---- EvtVarTypeNull [5] 0 ---- EvtVarTypeNull [6] 0 ---- EvtVarTypeNull [7] 5 ---- ArrayCount 1 ---- EvtVarTypeString "Application" 1 ---- EvtVarTypeString "System" 1 ---- EvtVarTypeString "Microsoft-Windows-EventLog/Admin" 1 ---- EvtVarTypeString "Microsoft-Windows-NTFS/operational" 1 ---- EvtVarTypeString "Setup" [8] 5 ---- ArrayCount 8 ---- EvtVarTypeUint32 10 ---- ChannelReferenceIndex 8 ---- EvtVarTypeUint32 10 ---- ChannelReferenceIndex 8 ---- EvtVarTypeUint32 10 ---- ChannelReferenceIndex 8 ---- EvtVarTypeUint32 10 ---- ChannelReferenceIndex 8 ---- EvtVarTypeUint32 10 ---- ChannelReferenceIndex [9] 5 ---- ArrayCount 8 ---- EvtVarTypeUint32 0 ---- ChannelreferenceID 8 ---- EvtVarTypeUint32 1 ---- ChannelreferenceID 8 ---- EvtVarTypeUint32 2 ---- ChannelreferenceID 8 ---- EvtVarTypeUint32 3 ---- ChannelreferenceID 8 ---- EvtVarTypeUint32 4 ---- ChannelreferenceID [10] 5 ---- ArrayCount 8 ---- EvtVarTypeUint32 0 ---- ChannelreferenceFlags 8 ---- EvtVarTypeUint32 0 ---- ChannelreferenceFlags 8 ---- EvtVarTypeUint32 0 ---- ChannelreferenceFlags 8 ---- EvtVarTypeUint32 0 ---- ChannelreferenceFlags 8 ---- EvtVarTypeUint32 0 ---- ChannelreferenceFlags [11] 5 ---- ArrayCount 8 ---- EvtVarTypeUint32 10000 ---- ChannelreferenceMessageID 8 ---- EvtVarTypeUint32 10001 ---- ChannelreferenceMessageID 8 ---- EvtVarTypeUint32 10002 ---- ChannelreferenceMessageID 8 ---- EvtVarTypeUint32 10003 ---- ChannelreferenceMessageID 8 ---- EvtVarTypeUint32 10004 ---- ChannelreferenceMessageID [12] 0 ---- EvtVarTypeNull [13] 0 ---- EvtVarTypeNull [14] 0 ---- EvtVarTypeNull [...] ---- Entries 15 through 27, which are also EvtVarTypeNull, have been omitted [28] 0 ---- EvtVarTypeNullThe server assigns the pointer of the publisher metadata object to the output parameter pubMetadata as the publisher metadata context handle.
After obtaining the publisher metadata context handle, the client calls the EvtRpcGetEventMetadataEnum method (section 3.1.4.27) to open the enumeration for the publisher's event metadata.
error_status_t EvtRpcGetEventMetadataEnum( [in, context_handle] PCONTEXT_HANDLE_PUBLISHER_METADATA pubMetadata = {handle from step 2}, [in] DWORD flags = 0, [in, unique, range(0, MAX_RPC_FILTER_LENGTH), string] LPCWSTR reservedForFilter = NULL, [out, context_handle] PCONTEXT_HANDLE_EVENT_METADATA_ENUM* eventMetaDataEnum );The server reads the publisher resource file and locates the event metadata section (as specified in section 3.1.1.14). The server then creates the event metadata object. After the server creates the object, it sets the values of the data fields in the object as follows:
HandleType: 5. Indicates the event metadata type.
EventsMetaData: 0x001ABEC8. A pointer to the event metadata section.
Enumerator: 0
The server assigns the pointer of the event metadata object to the output parameter eventMetadataEnum as the event metadata enumeration context handle.
After obtaining the eventMetaDataEnum context handle, the client calls the EvtRpcGetNextEventMetadata method (section 3.1.4.28) to get the event metadata information.
error_status_t EvtRpcGetNextEventMetadata( [in, context_handle] PCONTEXT_HANDLE_EVENT_METADATA_ENUM eventMetaDataEnum = {handle from step 3}, [in] DWORD flags = 0, [in] DWORD numRequested = 2, [out] DWORD* numReturned, [out, size_is(,*numReturned), range(0, MAX_RPC_EVENT_METADATA_COUNT)] EvtRpcVariantList** eventMetadataInstances );In this example method call, the client requests metadata for the first two events.
The server reads the metadata for the first two events from the publisher's resource file and fills the data into the eventMetadataInstances output parameter as follows:
8 ---- The count of the EvtRpcVariant of the first EvtRpcVariant list. 1001 ---- The EventID value. 1 ---- The Event version. 0 ---- The ChannelIndex value. 16 ---- The Level value. 10 ---- The Opcode value. 5 ---- The Task value. 0xFFFFFFFF ---- The keywords mask value. 10001 ---- The MessageID value for the event description string. <template tid="T22"> <data inType="win:UInt32" name="ErrorCode"/> <data inType="win:UnicodeString" name="Path"/> <UserData> <Error Code="%1"/> <ChannelPath>%2</ChannelPath> </UserData> </template> ---- The EvtVarTypeString value. 8 ---- The count of the EvtRpcVariant of the second EvtRpcVariant list. 1002 ---- The EventID value. 1 ---- The Event version. 0 ---- The ChannelIndex value. 16 ---- The Level value. 11 ---- The Opcode value. 6 ---- The Task value. 0xFFFFFFFF ---- The keywords mask value. 10002 ---- The MessageID value for the event description string. <template tid="T22"> <data inType="win:UInt32" name="ErrorCode"/> <data inType="win:UnicodeString" name="Path"/> <data inType="win:UnicodeString" name="NewLogFilePath"/> <UserData> <Error Code="%1"/> <ChannelPath>%2</ChannelPath> <NewLogFilePath>%3</NewLogFilePath> </template> ---- The EvtVarTypeString value.
The client can call the EvtRpcGetNextEventMetadata method repeatedly to obtain metadata for additional events.
When the client finishes, it calls the EvtRpcClose method (section 3.1.4.33) to close both the event metadata enumeration context handle and the publisher metadata context handle.
error_status_t EvtRpcClose( [in, out, context_handle] void** handle = eventMetaDataEnum ); error_status_t EvtRpcClose( [in, out, context_handle] void** handle = pubMetaData );