Events
Nov 19, 11 PM - Nov 21, 11 PM
Gain the competitive edge you need with powerful AI and Cloud solutions by attending Microsoft Ignite online.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Writes an ETW event that uses the current thread's activity ID.
ULONG EVNTAPI EventWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
[in] RegHandle
Registration handle of the provider. The handle comes from EventRegister. The generated event will use the ProviderId associated with the handle.
[in] EventDescriptor
EVENT_DESCRIPTOR with event information (metadata) including ID, Version, Level, Keyword, Channel, Opcode, and Task.
Important
ProviderId, Level and Keyword are the primary means for filtering events. Other kinds of filtering are possible but have much higher overhead. Always assign a nonzero level and keyword to every event.
[in] UserDataCount
Number of EVENT_DATA_DESCRIPTOR structures in UserData. The maximum number is 128.
[in, optional] UserData
An array of UserDataCount EVENT_DATA_DESCRIPTOR structures that describe the data to be included in the event. UserData may be NULL if UserDataCount is zero.
Each EVENT_DATA_DESCRIPTOR describes one block of memory to be included in the event. The specified blocks will be concatenated in order with no padding or alignment to form the event content. If using manifest-based decoding, the event content must match the layout specified in the template associated with the event in the manifest.
Returns ERROR_SUCCESS if successful or an error code. Possible error codes include the following:
The error code is primarily intended for use in debugging and diagnostic scenarios. Most production code should continue to run and continue to report events even if an ETW event could not be written, so release builds should usually ignore the error code.
Most event providers will not call EventWrite directly. Instead, most event providers are implemented using an ETW framework that wraps the calls to EventRegister, EventWrite, and EventUnregister. For example, you might write an event manifest and then use the Message Compiler to generate C/C++ code for the events, or you might use TraceLogging to avoid the need for a manifest.
EventWrite will route the event to the appropriate trace sessions based on the ProviderId (determined from the RegHandle), Level, Keyword, and other event characteristics. If no trace sessions are recording this event, this function will do nothing and return ERROR_SUCCESS.
To reduce the performance impact of events that are not recorded by any trace session, you can call EventEnabled to determine whether any trace session is recording your event before preparing the data and calling EventWrite.
EventWrite sets the event's activity ID to the current thread's activity ID. EventWrite does not include a related activity ID in the event. To specify a different activity ID or to add a related activity ID, use EventWriteTransfer.
EventWrite is equivalent to EventWriteEx with 0 for Filter, 0 for Flags, NULL for ActivityId, and NULL for RelatedActivityId.
Requirement | Value |
---|---|
Minimum supported client | Windows Vista [desktop apps | UWP apps] |
Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
Target Platform | Windows |
Header | evntprov.h |
Library | Advapi32.lib |
DLL | Advapi32.dll |
Events
Nov 19, 11 PM - Nov 21, 11 PM
Gain the competitive edge you need with powerful AI and Cloud solutions by attending Microsoft Ignite online.
Register now