EtwEventWriteTransfer

An event provider calls this function to write an event. The additional data that can be written through this function instead of EtwEventWrite allows for relating the event to other events.

Declaration

ULONG
EtwEventWriteTransfer (
    REGHANDLE RegHandle,
    EVENT_DESCRIPTOR const *EventDescriptor,
    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 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 RelatedActivityId argument tags the event as being related to the activity of some other event. This argument is optional in most versions but is required in version 6.0.

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 EtwEventWriteTransfer function is exported by name from NTDLL.DLL in version 6.0 and higher. Well-behaved software does not call this function but instead calls EventWriteTransfer, which is exported by name from ADVAPI32.DLL in version 6.0 and higher as a forward to EtwEventWriteTransfer.

Documentation Status

As with many NTDLL exports, Microsoft does not document EtwEventWriteTransfer. The higher-level ADVAPI32 function EventWriteTransfer is documented.

A C-language declaration of EtwEventWriteTransfer 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.

Behaviour

The RelatedActivityId argument is required in version 6.0, else the function returns ERROR_INVALID_PARAMETER.

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.