etwWriteEx 函数 (wdm.h)
EtwWriteEx 函数是一个跟踪函数，用于发布支持在内核模式驱动程序代码中筛选的事件。
语法
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
);
参数
[in] RegHandle
指向事件提供程序注册句柄的指针，如果事件提供程序注册成功， 则 EtwRegister 函数将返回该句柄。
[in] EventDescriptor
指向 EVENT_DESCRIPTOR 结构的指针。
[in] Filter
标识事件不会写入到的会话的实例标识符。 也就是说，该值是应从日志记录中排除的会话掩码， (筛选出) 。 使用按位 OR 指定多个标识符。 如果不支持筛选器，或者事件正在写入所有会话 (没有筛选器失败) ，则设置为零。 有关获取会话标识符的信息，请参阅 EtwEnableCallback 回调的 FilterData 参数。
[in] Flags
保留。 必须为零 (0) 。
[in, optional] ActivityId
指示与事件关联的活动的标识符。 ActivityID 提供了一种对相关事件进行分组的方法，用于端到端跟踪。 如果为 NULL，则 ETW 从线程本地存储获取标识符。 有关获取此标识符的详细信息，请参阅 EtwActivityIdControl。
[in, optional] RelatedActivityId
上一个组件的活动标识符。 使用该参数可以将您的组件的事件链接到上一个组件的事件。 若要获取为上一个组件设置的活动标识符，请参阅 EtwActivityIdControl 函数的 ControlCode 参数的说明。
[in] UserDataCount
UserData 中的EVENT_DATA_DESCRIPTOR结构数。 最大数字为 128。
[in, optional] UserData
指向EVENT_DATA_DESCRIPTOR结构的数组的指针。 如果 UserDataCount 为零，请将此参数设置为 NULL。 该数据必须采用清单中所指定的顺序。
返回值
如果成功，则返回ERROR_SUCCESS或错误时返回以下值之一。
注解
EtwWriteEx 函数是用户模式 EventWriteEx 函数的内核模式等效函数。 使用此函数写入的事件数据需要清单。 清单嵌入到提供程序中，因此该提供程序必须可供使用者使用数据。 为了确保要发布的事件有使用者，可以在调用 EtwWrite 之前调用 EtwEventEnabled 或 EtwProviderEnabled。
如果要在端到端跟踪方案中关联不同组件中的事件，请使用 ActivityId 和 RelatedActivityId 参数。 例如，组件 A、B 和 C 对相关活动执行工作，并希望链接其事件，以便使用者可以使用与该活动相关的所有事件。
可以在任何 IRQL 中调用 EtwWriteEx 。 但是，当 IRQL 大于 APC_LEVEL时，传递给 EtwWrite、EtwWriteEx、EtwWriteString、EtwWriteTransfer 函数的任何数据不得分页。 也就是说，在大于 APC_LEVEL 的 IRQL 上运行的任何内核模式例程都无法访问可分页内存。 传递给 EtwWrite、 EtwWriteEx、 EtwWriteString 和 EtwWriteTransfer 函数的数据必须驻留在系统空间内存中，而不管 IRQL 是什么。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 7 |
| 最低受支持的服务器 | Windows Server 2008 R2 |
| 目标平台 | 通用 |
| 标头 | wdm.h |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |