Edit

EventDefinitionType Complex Type

  • Article

Defines an event that your provider can write.

<xs:complexType name="EventDefinitionType">
    <xs:simpleContent>
        <xs:extension
            base="string"
        >
            <xs:attribute name="value"
                type="UInt32Type"
                use="required"
             />
            <xs:attribute name="level"
                type="QName"
                use="optional"
             />
            <xs:attribute name="template"
                type="token"
                use="optional"
             />
            <xs:attribute name="channel"
                type="token"
                use="optional"
             />
            <xs:attribute name="keywords"
                type="QNameList"
                use="optional"
             />
            <xs:attribute name="task"
                type="QName"
                use="optional"
             />
            <xs:attribute name="opcode"
                type="QName"
                use="optional"
             />
            <xs:attribute name="symbol"
                type="CSymbolType"
                use="optional"
             />
            <xs:attribute name="version"
                type="unsignedByte"
                use="optional"
             />
            <xs:attribute name="message"
                type="strTableRef"
                use="optional"
             />
            <xs:attribute name="notLogged"
                type="boolean"
                use="optional"
                default="false"
             />
        </xs:extension>
    </xs:simpleContent>
</xs:complexType>

Attributes

Name Type Description
channel token An identifier that identifies the channel to where the event is written. Specify a channel identifier of one of the channels that you defined or imported. If the channel does not specify a channel identifier, use the channel's name. For details on defining or importing a channel, see the ChannelListType complex type.
If you do not specify a channel, the event is not written to a channel. Typically, the only reason not to specify a channel is if you are writing events only to an ETW session. For details, see creating an ETW session, see Controlling Event Tracing Sessions.
keywords QNameList A space-separated list of keyword names that identify the category of events to which this event belongs. Specify a keyword name from the list of keywords that you define. For details on defining keywords, see the KeywordType complex type.
If you do not specify keywords, the event descriptor will contain a zero for keywords.
level QName The level of verbosity to use when writing the event. Specify the name of a level that you defined in the manifest or one of the levels defined in the \Include\Winmeta.xml file that is included in the Windows SDK. For details on defining a level, see the LevelType complex type.
If you do not specify a level, the event descriptor will contain a zero for level.
You must specify a level if the channel type to which the event is written is Admin; the level must be one of the following levels defined in Winmeata.xml:
  • win:Critical
  • win:Error
  • win:Warning
  • win:Informational
message strTableRef The localized message for the event. The message string references a localized string in the stringTable section of the manifest.
You must specify a message if the channel type to which the event is written is Admin.
notLogged boolean Determines whether the provider logs this event. Specify true if the provider logs this event; otherwise, false. Use this attribute to indicate that the provider is no longer logging this event instead of removing the event from the manifest. Retaining the event in the manifest will let consumers decode older etl files that include the event.
Windows Server 2008 and Windows Vista: This attribute is not supported in versions of the message compiler that shipped prior to the Windows 7 version of the Windows SDK.
opcode QName The name of an opcode that identifies an operation within the task. Specify the name of an opcode that you defined in the manifest or one of the opcodes defined in Winmeta.xml. For details on defining an opcode, see the OpcodeType complex type.
If the task that you reference contains task-specific (local) opcodes, you can specify one of its task-specific opcodes or an opcode defined at the provider level (a global opcode). If you specify a global opcode, the value of the global opcode cannot be the same as one of the local opcodes for the task.
If you reference a local opcode, the task attribute must reference the task to which the local opcode belongs.
If you do not specify an opcode, the event descriptor will contain a zero for opcode.
symbol CSymbolType The symbol to use to reference the event descriptor for this event in your application. The Message Compiler (MC.exe) uses the symbol to create a constant for the event descriptor in the header file that the compiler generates. If you do not specify a symbol, the compiler generates one for you. You use the descriptor when you call the EventWrite function to write the event.
task QName The name of a task that identifies the component or subcomponent that generates this event. Specify the name of a task that you defined in the manifest. For details on defining a task, see the TaskType complex type.
If you do not specify a task, the event descriptor will contain a zero for task.
template token The template identifier of the template that defines the data items that this event includes. Specify the identifier of a template that you defined in the manifest. For details on defining a template, see the TemplateItemType complex type.
value UInt32Type The event identifier. The identifier must be unique within the list of events that you define.
version unsignedByte A one-byte version number of the event definition.

Remarks

If you use EvtFormatMessage to format the message string for the event (or use the Event Viewer to view the message string), the message string can contain insertion strings and any of the format strings that the Win32 FormatMessage function supports. The insertion strings are limited to %n or %n!s! (for example, %1) where n is the one-based reference the data items defined in the event's template. The message string can also contain parameter insertion strings in the form %%n (for example, %%4). The maximum number of insertion strings that the message can contain is 100.

Requirements

Requirement Value
Minimum supported client
 Windows Vista [desktop apps only]
Minimum supported server
 Windows Server 2008 [desktop apps only]