EVENT_FILTER_DESCRIPTOR 结构 (evntprov.h)

项目
08/23/2023

EVENT_FILTER_DESCRIPTOR 结构定义会话传递给提供程序的 enable 回调函数的筛选器数据。

语法

typedef struct _EVENT_FILTER_DESCRIPTOR {
  ULONGLONG Ptr;
  ULONG     Size;
  ULONG     Type;
} EVENT_FILTER_DESCRIPTOR, *PEVENT_FILTER_DESCRIPTOR;

成员

Ptr

指向 Type 成员中指定的筛选器类型的筛选器数据的指针。

如果 Type 成员设置为 EVENT_FILTER_TYPE_PID， 则 Ptr 成员指向) (PID 的进程 ID 数组。

如果 Type 成员设置为 EVENT_FILTER_TYPE_EVENT_ID， 则 Ptr 成员指向包含事件 ID 数组和布尔值的 EVENT_FILTER_EVENT_ID 结构，该值确定指定事件 ID 是启用还是禁用跟踪。

如果 Type 成员设置为 EVENT_FILTER_TYPE_STACKWALK， 则 Ptr 成员指向一个 EVENT_FILTER_EVENT_ID 结构，该结构包含事件 ID 数组和一个布尔值，该值确定为指定的事件 ID 启用或禁用堆栈跟踪。

如果 Type 成员设置为 EVENT_FILTER_TYPE_SCHEMATIZED，请参阅 EVENT_FILTER_HEADER 结构，了解有关构造筛选器的详细信息。

Size

数据的大小（以字节为单位）。

最大数据大小限制取决于指定的 Type 成员 (筛选器) 的类型。许多筛选器类型的最大数据大小（以字节为单位）限制为 MAX_EVENT_FILTER_DATA_SIZE，在 evntprov.h 头文件中定义为 1024。

Type

标识筛选器的提供程序定义的值。对于检测清单中定义的筛选器，将此成员设置为 EVENT_FILTER_TYPE_SCHEMATIZED。

此成员的可能值在 evntprov.h 头文件中定义。

EVENT_FILTER_TYPE_NONE (0x00000000)

无筛选器。
EVENT_FILTER_TYPE_SCHEMATIZED (0x80000000)

架构化筛选器。

这是传统的筛选设置，也称为提供程序端筛选。控制器将一组自定义筛选器定义为在 EnableTrace、EnableTraceEx 或 EnableTraceEx2 调用中传递给提供程序的二进制对象。控制器和提供程序有责任定义和解释这些筛选器，并且控制器应仅记录适用的事件。这需要控制器和提供程序的紧密耦合，因为未定义可筛选的二进制对象的类型和格式。 TdhEnumerateProviderFilters 函数可用于检索清单中定义的筛选器。

有关架构化筛选器的详细信息，请参阅定义筛选器。
EVENT_FILTER_TYPE_SYSTEM_FLAGS (0x80000001)

保留以供内部使用。
EVENT_FILTER_TYPE_TRACEHANDLE (0x80000002)

用于捕获特定跟踪会话的断开。传递给 EnableTraceEx 函数的 ControlCode 参数必须设置为 EVENT_CONTROL_CODE_CAPTURE_STATE，ProviderId 参数必须是 SystemTraceControlGuid。 EVENT_FILTER_DESCRIPTOR 结构应指向表示当前 ETW 会话的单个 TRACEHANDLE。将为该特定会话执行断开。
EVENT_FILTER_TYPE_PID (0x80000004)

进程 ID。这是范围筛选器之一。

根据进程 ID 筛选 ETW 事件将导致事件流 (文件或实时) ，仅包含来自指定进程中提供程序的事件。它只会在提供 PID 的进程中启用提供程序。 PID 列表是调用 EnableTraceEx2 时正在运行的进程 PID，并将在该特定时间) 提供 PID 的所有进程 (启用提供程序。 PID 列表不会存储在会话中。因此，当进程终止并再次出现时，它中的提供程序不会自动启用到跟踪会话。基于 PID 的 filter-blob 仅对内核模式记录器会话有效，因为专用记录器会话在用户模式进程中运行。

可以筛选的进程 ID 的最大数目受 evntprov.h 头文件中定义的MAX_EVENT_FILTER_PID_COUNT限制为 8。

如果提供了进程 ID 筛选器，则将仅在用户模式进程中启用提供程序。如果内核模式驱动程序注册了同一提供程序，则不会启用该提供程序。

这与系统范围的专用记录器 EVENT_TRACE_PROPERTIES_V2 一起使用。
EVENT_FILTER_TYPE_EXECUTABLE_NAME (0x80000008)

可执行文件名称。这是范围筛选器之一。

这与系统范围的专用记录器 EVENT_TRACE_PROPERTIES_V2 一起使用。
EVENT_FILTER_TYPE_PACKAGE_ID (0x80000010)

包 ID。这是范围筛选器之一

这可用于筛选从特定 Windows 应用商店应用包发出的事件的提供程序。
EVENT_FILTER_TYPE_PACKAGE_APP_ID (0x80000020)

PRAID) (包相对应用 ID。这是范围筛选器之一

这可用于筛选从特定 Windows 应用商店应用包发出的事件的提供程序。
EVENT_FILTER_TYPE_PAYLOAD (0x80000100)

事件有效负载 (事件) 的内容。

事件有效负载筛选器的最大数据大小（以字节为单位）限制为在 evntprov.h 头文件中定义的MAX_EVENT_FILTER_PAYLOAD_SIZE为 4096。
EVENT_FILTER_TYPE_EVENT_ID (0x80000200)

事件 ID。

此功能允许启用或禁用对事件列表的筛选。提供的筛选器包括一个 EVENT_FILTER_EVENT_ID 结构，该结构包含一个事件 ID 数组和一个布尔值，该值指示是启用或禁用对指定事件的筛选。每个事件写入调用都将快速完成此数组，以确定是启用或禁用记录事件。

应用于 TraceLogging 提供程序时，此筛选器将被忽略，因为 TraceLogging 事件没有静态事件 ID。

EVENT_FILTER_EVENT_ID 结构中允许的最大事件 ID 数受 evntprov.h 头文件中定义的MAX_EVENT_FILTER_EVENT_ID_COUNT限制为 64。
EVENT_FILTER_TYPE_EVENT_NAME (0x80000400)

TraceLogging 事件名称。

此功能允许根据事件的名称启用或禁用 TraceLogging 事件。提供的筛选器包括一个EVENT_FILTER_EVENT_NAME结构，该结构包含事件名称数组、关键字 (keyword) 位掩码和要筛选的级别，以及一个指示是启用或禁用所描述事件的布尔值。应用于非 TraceLogging 提供程序时，将忽略此筛选器，因为这些事件没有在其有效负载中指定名称。

注意：适用于 Windows 10 版本 1709 及更高版本。
EVENT_FILTER_TYPE_STACKWALK (0x80001000)

堆栈遍地。

为提供程序启用堆栈遍走后，将针对提供程序生成的所有事件捕获堆栈。大多数情况下，用户只对来自特定数量的事件的堆栈感兴趣。

此功能允许启用或禁用对事件列表进行堆栈浏览。提供的筛选器包括一个 EVENT_FILTER_EVENT_ID 结构，该结构包含一个事件 ID 数组和一个布尔值，该值指示是为指定事件启用或禁用堆栈捕获。每个事件写入调用都将快速完成此数组，以确定是否应捕获堆栈。

应用于 TraceLogging 提供程序时，此筛选器将被忽略，因为 TraceLogging 事件没有静态事件 ID。

如果选择使用此筛选器，在为要从提供程序收集任何堆栈启用提供程序时，仍必须在ENABLE_TRACE_PARAMETERS结构中指定EVENT_ENABLE_PROPERTY_STACK_TRACE。

EVENT_FILTER_EVENT_ID 结构中允许的最大事件 ID 数受 evntprov.h 头文件中定义的MAX_EVENT_FILTER_EVENT_ID_COUNT限制为 64。

注意：适用于 Windows 10 版本 1709 及更高版本。
EVENT_FILTER_TYPE_STACKWALK_NAME (0x80002000)

TraceLogging 事件名称。

此功能允许根据事件名称筛选 TraceLogging 事件的堆栈集合。提供的筛选器包括一个EVENT_FILTER_EVENT_NAME结构，该结构包含事件名称数组、关键字 (keyword) 位掩码和要筛选的级别，以及一个布尔值，该值指示是否为所述事件收集堆栈。

应用于非 TraceLogging 提供程序时，将忽略此筛选器，因为这些事件没有在其有效负载中指定名称。

如果选择使用此筛选器，在为从提供程序收集任何堆栈启用提供程序时，仍必须在ENABLE_TRACE_PARAMETERS结构上指定EVENT_ENABLE_PROPERTY_STACK_TRACE。

注意：适用于 Windows 10 版本 1709 及更高版本。
EVENT_FILTER_TYPE_STACKWALK_LEVEL_KW (0x80004000)

事件级别和关键字 (keyword) 。

此功能允许根据事件的级别和关键字 (keyword) 筛选事件的堆栈集合。提供的筛选器包括一个EVENT_FILTER_LEVEL_KW结构，该结构包含要筛选的关键字 (keyword) 位掩码和级别，以及一个布尔值，该值指示是否收集所描述事件的堆栈。

如果选择使用此筛选器，在为从提供程序收集任何堆栈启用提供程序时，仍必须在ENABLE_TRACE_PARAMETERS结构上指定EVENT_ENABLE_PROPERTY_STACK_TRACE。

注意：适用于 Windows 10 版本 1709 及更高版本。

备注

提供程序确定数据的布局及其用途。

在 Windows 8.1、Windows Server 2012 R2 及更高版本上，EnableTraceEx2 函数和ENABLE_TRACE_PARAMETERS和EVENT_FILTER_DESCRIPTOR结构可以使用事件有效负载、作用域和堆栈遍查筛选器来筛选记录器会话中的特定条件。有关事件有效负载筛选器的详细信息，请参阅 EnableTraceEx2、 TdhCreatePayloadFilter 和 TdhAggregatePayloadFilters 函数以及 ENABLE_TRACE_PARAMETERS 和 PAYLOAD_FILTER_PREDICATE 结构。

要求


最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
标头	evntprov.h