Share via


EVENT_TRACE_HEADER structure

The EVENT_TRACE_HEADER structure is used to pass a WMI event to the WMI event logger. It is overlaid on the WNODE_HEADER portion of the WNODE_EVENT_ITEM passed to IoWMIWriteEvent. Information contained in the EVENT_TRACE_HEADER is written to the WMI log file.

Syntax

typedef struct _EVENT_TRACE_HEADER {
  USHORT        Size;
  union {
    USHORT FieldTypeFlags;
    struct {
      UCHAR HeaderType;
      UCHAR MarkerFlags;
    };
  };
  union {
    ULONG  Version;
    struct {
      UCHAR  Type;
      UCHAR  Level;
      USHORT Version;
    } Class;
  };
  ULONG         ThreadId;
  ULONG         ProcessId;
  LARGE_INTEGER TimeStamp;
  union {
    GUID      Guid;
    ULONGLONG GuidPtr;
  };
  union {
    struct {
      ULONG KernelTime;
      ULONG UserTime;
    };
    ULONG64 ProcessorTime;
    struct {
      ULONG ClientContext;
      ULONG Flags;
    };
  };
} EVENT_TRACE_HEADER, *PEVENT_TRACE_HEADER;

Members

  • Size
    Specifies the size, in bytes, of the buffer that is allocated to hold event tracing information. The value that is specified must include both the size of the EVENT_TRACE_HEADER structure and the size of any driver-specific data. (EVENT_TRACE_HEADER is overlaid on a WNODE_HEADER structure, but the Size member of EVENT_TRACE_HEADER and the BufferSize member of WNODE_HEADER do not specify the same size. Do not use the BufferSize member of WNODE_HEADER to set the Size member.)

  • FieldTypeFlags
    Flags to indicate which fields in the EVENT_TRACE_HEADER structure are valid.

  • HeaderType
    Reserved for internal use.

  • MarkerFlags
    Reserved for internal use.

  • Version
    Drivers can use this member to store version information. This information is not interpreted by the event logger.

  • Class
    Event class information.

    • Type
      Trace event type. This can be one of the predefined EVENT_TRACE_TYPE_XXX values contained in Evntrace.h or can be a driver-defined value. Callers are free to define private event types with values greater than the reserved values in Evntrace.h.

    • Level
      Trace instrumentation level. A driver-defined value meant to represent the degree of detail of the trace instrumentation. Drivers are free to give this value meaning. This value should be 0 by default. More information about how consumers can request different levels of trace information will be provided in a future version of the documentation.

    • Version
      Version of trace record. Version information that can be used by the driver to track different event formats.

  • ThreadId
    Thread identifier.

  • ProcessId
    Process identifier.

  • TimeStamp
    The time at which the driver event occurred. This time value is expressed in absolute system time format. Absolute system time is the number of 100-nanosecond intervals since the start of the year 1601 in the Gregorian calendar. If the WNODE_FLAG_USE_TIMESTAMP is set in Flags, the system logger will leave the value of TimeStamp unchanged. Otherwise, the system logger will set the value of TimeStamp at the time it receives the event. A driver can call KeQuerySystemTime to set the value of TimeStamp.

  • Guid
    The GUID that identifies the data block for the event.

  • GuidPtr
    If the WNODE_FLAG_USE_GUID_PTR flag bit is set in Flags, GuidPtr points to the GUID that identifies the data block for the event.

  • KernelTime
    Reserved for internal use.

  • UserTime
    Reserved for internal use.

  • ProcessorTime
    Reserved for internal use.

  • ClientContext
    Reserved for internal use.

  • Flags
    Provides information about the contents of this structure. For information about EVENT_TRACE_HEADER Flags values, see the Flags description in WNODE_HEADER.

Remarks

A driver that supports trace events will use this structure to report events to the WMI event logger. Trace events should not be reported until the driver receives a request to enable events and the control GUID is one the driver supports. The driver should initialize an EVENT_TRACE_HEADER structure, fill in any user-defined event data at the end, and pass a pointer to the EVENT_TRACE_HEADER to IoWMIWriteEvent. The driver should continue reporting trace events until it receives a request to disable the control GUID for the trace events.

If the driver does not specify the WNODE_FLAG_USE_MOF_PTR flag in the Flags member of EVENT_TRACE_HEADER, the EVENT_TRACE_HEADER structure is followed in memory by event-specific data. In this case, the Size member must be sizeof(EVENT_TRACE_HEADER) plus the size of the event-specific data.

If the driver does specify the WNODE_FLAG_USE_MOF_PTR flag, the EVENT_TRACE_HEADER structure is followed in memory by an array of MOF_FIELD structures (which are defined in Evntrace.h) that contain pointers to the data and sizes rather than the event tracing data itself. In this case, the Size member must be sizeof(EVENT_TRACE_HEADER) plus the size of the array of MOF_FIELD structures.

Requirements

Header

Evntrace.h (include Wdm.h or Ntddk.h)

See also

IoWMIWriteEvent

WNODE_EVENT_ITEM

WNODE_HEADER

 

 

Send comments about this topic to Microsoft