EtwEventWriteFull

An event provider calls this function to write an event. Like EtwEventWriteTransfer, this function allows for relating the event to others. It also can set event properties that are not supported through any other Event API function.

Declaration

ULONG
EtwEventWriteFull (
    REGHANDLE RegHandle,
    EVENT_DESCRIPTOR const *EventDescriptor,
    USHORT EventProperty, 
    GUID const *ActivityId, 
    GUID const *RelatedActivityId, 
    ULONG UserDataCount,
    EVENT_DATA_DESCRIPTOR *UserData);

Parameters

The required RegHandle argument identifies which registration of an event provider is writing the event.

The required EventDescriptor argument tells which event is to be written.

The EventProperty argument is a set of bit flags that elaborate the event’s intended interpretation.

The optional ActivityId argument tags the event with an identifier that other events may refer to as their related activity. This argument can be NULL to stand for whatever activity identifier is current set for the calling thread.

The optional RelatedActivityId argument tags the event as being related to the activity of some other event.

The optional UserDataCount and UserData arguments are respectively the element count and address of an array of structures that supply event-specific data to record with the event.

Return Value

The function returns zero for success, else a Win32 error code.

Availability

The EtwEventWriteFull function is exported by name from NTDLL.DLL in version 6.0 and higher.

Documentation Status

As with many NTDLL functions, Microsoft does not document EtwEventWriteFull. Unlike many, no higher-level function corresponds roughly to it. Though other NTDLL functions whose names begin with EtwEventWrite are exported without the Etw prefix as forwards from ADVAPI32, this one is missed.

A C-language declaration of EtwEventWriteFull is published by Microsoft in a file named NTETW.H in the Enterprise edition of the Windows Driver Kit (WDK) for Windows 10 Version 1511.

Or so things stood. Apparently too late for a downloadable package of documentation in 2017 but now dated to 2018 online, Microsoft documented EtwEventWriteFull among some Developer Notes. It is there said explicitly to be internal. Among the Requirements is the Header named ntetw.h which Microsoft is not known to have published except in the one case above.

Behaviour

The EtwEventWriteFull function exists only as an embellishment of EtwEventWriteTransfer, specifically to add the EventProperty argument.

General Event Writing

If EventDescriptor is NULL, the function has no event to write: it returns ERROR_INVALID_PARAMETER.

If the RegHandle is not valid, the function has no event provider to write an event from: it returns ERROR_INVALID_HANDLE. A valid REGHANDLE is produced by the EtwEventRegister function and is made invalid by EtwEventUnregister.

Event providers send events into the ETW mechanism. Tracing sessions receive them. Each tracing session chooses which event providers they want events from. For each event provider that they so enable, a tracing session may also specify a level and keyword to match against events from that provider. In later versions, they may also specify properties that affect the matching. If the Level and Keyword in at EventDescriptor match this specification, then the event is said to be enabled for the session.

If the event is enabled for any private tracing session, the function writes the event to the user-mode tracing buffers of each such session for which the event is enabled. Failure to write to any such session is failure for the function.

If the event is enabled for any tracing session that is managed by the kernel, the function sends the event to the kernel for distribution to each tracing session for which the event is enabled. Inputs and defaults are packaged as an EVENT_HEADER for NtTraceEvent with ETW_NT_FLAGS_TRACE_EVENT as its Flags argument. Failure from the kernel is failure for the function.

Event Properties

Microsoft’s EVNTCONS.H defines four bits for the EventProperties argument:

These values for the EventProperty argument are documented for another purpose, in the EventProperty member of the EVENT_HEADER structure that describes an event when delivered to a consumer.

Use by Microsoft

When this article was new, i.e., for Windows Vista, three users were known of this function:

• crypt32.dll, wecsvc.dll and wevtapi.dll

Yes, they use one each of the flags that are defined for EventProperty. There is also an internal use of EVENT_HEADER_PROPERTY_LEGACY_EVENTLOG for the EtwEventWriteString function.