TdhCreatePayloadFilter 函数 (tdh.h)

项目
08/26/2023

TdhCreatePayloadFilter 函数为要与 EnableTraceEx2 函数一起使用的单个有效负载创建单个筛选器。

语法

TDHSTATUS TdhCreatePayloadFilter(
  [in]  LPCGUID                   ProviderGuid,
  [in]  PCEVENT_DESCRIPTOR        EventDescriptor,
  [in]  BOOLEAN                   EventMatchANY,
  [in]  ULONG                     PayloadPredicateCount,
  [in]  PPAYLOAD_FILTER_PREDICATE PayloadPredicates,
  [out] PVOID                     *PayloadFilter
);

参数

[in] ProviderGuid

标识 EventDescriptor 参数的清单提供程序的 GUID。

[in] EventDescriptor

指向将筛选其有效负载的事件描述符的指针。

[in] EventMatchANY

一个布尔值，指示指定多个条件时如何处理事件。

当此参数为 TRUE 时，如果筛选器中指定的任何指定条件为 TRUE，则将事件写入会话。

如果此参数为 FALSE，则仅当筛选器中指定的所有指定条件均为 TRUE 时，才会将事件写入会话。

[in] PayloadPredicateCount

筛选器中指定的条件数。此值必须小于或等于 Tdh.h 头文件中定义的ETW_MAX_PAYLOAD_PREDICATES常量。

[in] PayloadPredicates

指向包含筛选器指定的列表条件的 PAYLOAD_FILTER_PREDICATE 结构的数组的指针。

[out] PayloadFilter

成功后，此参数返回指向针对指定条件正确调整大小和生成的单个有效负载筛选器的指针。

调用方使用返回的有效负载筛选器和 EnableTraceEx2 函数完成时，应调用 TdhDeletePayloadFilter 函数以释放分配的内存。

返回值

如果成功，则返回ERROR_SUCCESS。否则，除了其他返回代码之外，此函数还返回以下返回代码之一。

返回代码	说明
ERROR_FILE_NOT_FOUND	找不到提供程序的元数据。
ERROR_INVALID_PARAMETER	一个或多个参数无效。
ERROR_INSUFFICIENT_BUFFER	生成的有效负载筛选器不符合 EnableTraceEx2 函数对有效负载中EVENT_FILTER_DESCRIPTOR结构施加的MAX_EVENT_FILTER_PAYLOAD_SIZE限制。
ERROR_NOT_ENOUGH_MEMORY	无法分配内存来创建有效负载筛选器。
ERROR_NOT_FOUND	找不到提供的提供程序 GUID 的架构信息。

注解

在 Windows 8.1、Windows Server 2012 R2 及更高版本中，EnableTraceEx2 函数可以使用事件有效负载筛选器来筛选记录器会话中事件的特定内容。

TdhCreatePayloadFilter 函数用于为要与 EnableTraceEx2 函数一起使用的单个有效负载创建单个有效负载筛选器。 TdhCreatePayloadFilter 为单个有效负载筛选器分配和填充不透明的数据结构。当不再需要有效负载筛选器时， TdhDeletePayloadFilter 函数用于释放为有效负载筛选器分配的内存。

对于单个提供程序，多个事件可以具有不同的有效负载筛选器。对于同一事件，还可以有多个筛选器，如果有任何或所有事件的筛选器通过该有效负载，则会将有效负载传递给会话。

EnableTraceEx2 函数采用 enableParameters 参数中传递的ENABLE_TRACE_PARAMETERS结构中的EVENT_FILTER_DESCRIPTOR结构数组。对于每个事件筛选器类型，数组中只能有一个条目。 TdhAggregatePayloadFilters 函数可用于将使用 TdhCreatePayloadFilter 创建的单个提供程序的有效负载筛选器列表聚合到单个数据结构中，并返回用于 EnableTraceEx2 函数的EVENT_FILTER_DESCRIPTOR。

示例

有关使用 TdhCreatePayloadFilter 函数创建有效负载筛选器以用于筛选记录器会话中特定条件的示例，请参阅 EnableTraceEx2 函数的示例。

要求


最低受支持的客户端	Windows 8.1 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 R2 [仅限桌面应用]
目标平台	Windows
标头	tdh.h
Library	Tdh.lib
DLL	Tdh.dll