PEVENT_CALLBACK callback function (evntrace.h)

Article
05/24/2022

ETW event consumers implement this callback to receive events from a trace processing session. This callback should not be used in new code. Instead, implement EventRecordCallback.

The PEVENT_CALLBACK type is a pointer to this callback function. EventCallback is a placeholder for the application-defined function name.

Syntax

PEVENT_CALLBACK PeventCallback;

void PeventCallback(
  [in] PEVENT_TRACE pEvent
)
{...}

Parameters

[in] pEvent

Pointer to an EVENT_TRACE structure that contains the event information.

Return value

None

Remarks

Note

This callback is obsolete because it receives incomplete information about the event and is not compatible with event decoding helper APIs such as TdhGetEventInformation. Instead of implementing EventCallback, implement EventRecordCallback.

To specify the function that ETW calls to deliver the events, set the EventCallback member of the EVENT_TRACE_LOGFILE structure that you pass to the OpenTrace function.

Note

If your EventCallback function is receiving garbled data from ProcessTrace, double-check the flags specified in the ProcessTraceMode field of the EVENT_TRACE_LOGFILE structure that was provided to OpenTrace. EVENT_TRACE_LOGFILE's EventCallback and EventRecordCallback fields are overlapping members of a union. If the ProcessTraceMode field includes the PROCESS_TRACE_MODE_EVENT_RECORD flag, ProcessTrace will invoke your callback using the EventRecordCallback function signature. Otherwise, ProcessTrace will invoke your callback using the EventCallback function signature.

After using OpenTrace to create the trace processing session, call the ProcessTrace function to begin receiving the events.

When ProcessTrace begins processing events from a trace, it may invoke your callback with one or more synthetic events that contain data about the trace (metadata) rather than data from logged events. These synthetic events have Header.Guid set to EventTraceGuid and Header.Class.Type set based on the content of the synthetic event. For example, the first event from each trace file will be a synthetic event with type 0 containing TRACE_LOGFILE_HEADER information.

All the other events you receive contain provider-specific event data. You use the Header.Guid and Header.Class.Type members of EVENT_TRACE to determine the type of event you received. It is possible to hard-code decoding logic for well-known event types, but most events will be decoded using MOF schema information registered on the system in the \\root\wmi namespace. For information on using an event's MOF schema to interpret the event, see Consuming Events.

Examples

For an example implementation of an EventCallback function, see Retrieving Event Data Using MOF.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	evntrace.h