Edit

EtwWriteEx function (wdm.h)

  • Article

The EtwWriteEx function is a tracing function for publishing events that support filtering in your kernel-mode driver code.

Syntax

NTSTATUS EtwWriteEx(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG64                Filter,
  [in]           ULONG                  Flags,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Parameters

[in] RegHandle

A pointer to the event provider registration handle, which is returned by the EtwRegister function if the event provider registration is successful.

[in] EventDescriptor

A pointer to the EVENT_DESCRIPTOR structure.

[in] Filter

The instance identifiers that identify the session to which the event will not written. That is, the value is a mask of sessions which should be excluded from logging (filtered out). Use a bitwise OR to specify multiple identifiers. Set to zero if you do not support filters or if the event is being written to all sessions (no filters failed). For information on getting the identifier for a session, see the FilterData parameter of your EtwEnableCallback callback.

[in] Flags

Reserved. Must be zero (0).

[in, optional] ActivityId

The identifier that indicates the activity associated with the event. The ActivityID provides a way to group related events and is used in end-to-end tracing. If NULL, ETW gets the identifier from the thread local storage. For details on getting this identifier, see EtwActivityIdControl.

[in, optional] RelatedActivityId

Activity identifier from the previous component. Use this parameter to link your component's events to the previous component's events. To get the activity identifier that was set for the previous component, see the descriptions for the ControlCode parameter of the EtwActivityIdControl function.

[in] UserDataCount

Number of EVENT_DATA_DESCRIPTOR structures in UserData. The maximum number is 128.

[in, optional] UserData

A pointer to the array of EVENT_DATA_DESCRIPTOR structures. Set this parameter to NULL if UserDataCount is zero. The data must be in the order specified in the manifest.

Return value

Returns ERROR_SUCCESS if successful or one of the following values on error.

Remarks

The EtwWriteEx function is the kernel-mode equivalent of the user-mode EventWriteEx function. Event data written with this function requires a manifest. The manifest is embedded in the provider, so the provider must be available for a consumer to consume the data. To ensure that there is a consumer for the event you are publishing, you can precede the call to EtwWrite with a call to EtwEventEnabled or EtwProviderEnabled.

Use the ActivityId and RelatedActivityId parameters when you want to relate events in different components in an end-to-end tracing scenario. For example, components A, B, and C perform work on a related activity and want to link their events so that a consumer can consume all the events related to that activity.

You can call EtwWriteEx at any IRQL. However, when IRQL is greater than APC_LEVEL, any data passed to the EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer functions must not be pageable. That is, any kernel-mode routine that is running at IRQL greater than APC_LEVEL cannot access pageable memory. Data passed to the EtwWrite, EtwWriteEx, EtwWriteString, and EtwWriteTransfer functions must reside in system-space memory, regardless of what the IRQL is.

Requirements

Requirement Value
Minimum supported client Windows 7
Minimum supported server Windows Server 2008 R2
Target Platform Universal
Header wdm.h
Library NtosKrnl.lib
DLL NtosKrnl.exe

See also

EtwWrite

EventWrite

EventWriteEx