TdhAggregatePayloadFilters 函数 (tdh.h)

项目
03/04/2024

TdhAggregatePayloadFilters 函数将单个提供程序的多个有效负载筛选器聚合到与 EnableTraceEx2 函数一起使用的单个数据结构中。

语法

TDHSTATUS TdhAggregatePayloadFilters(
                 ULONG                    PayloadFilterCount,
                 PVOID                    *PayloadFilterPtrs,
  [in, optional] PBOOLEAN                 EventMatchALLFlags,
  [out]          PEVENT_FILTER_DESCRIPTOR EventFilterDescriptor
);

参数

PayloadFilterCount

有效负载筛选器的计数。

PayloadFilterPtrs

事件有效负载单个筛选器的数组，每个筛选器都是通过调用 TdhCreatePayloadFilter 函数创建的。

[in, optional] EventMatchALLFlags

与 PayloadFilterPtrs 参数中传递的每个有效负载筛选器对应的布尔值数组，指示指定多个条件时如何处理事件。此参数仅影响为同一事件指定多个有效负载筛选器的情况。

当布尔值为 TRUE 时，如果筛选器中指定的任何条件为 TRUE，则将事件写入会话。如果在同一事件 ID 或事件版本的一个或多个筛选器上将此标志设置为 TRUE ，则仅当满足事件的所有已标记筛选器时，才会写入事件。

当布尔值为 FALSE 时，仅当筛选器中指定的所有指定条件均为 TRUE 时，事件才会写入会话。如果针对同一事件 ID 或事件版本的一个或多个筛选器将此标志设置为 FALSE ，则如果满足任何未标记的筛选器，则会写入该事件。

[out] EventFilterDescriptor

指向要与 EnableTraceEx2 函数一起使用的 EVENT_FILTER_DESCRIPTOR 结构的指针。 EVENT_FILTER_DESCRIPTOR 结构将包含指向此函数分配的聚合有效负载筛选器的指针。

当调用方完成将此 EVENT_FILTER_DESCRIPTOR 结构与 EnableTraceEx2 函数一起使用时，应调用 TdhCleanupPayloadEventFilterDescriptor 函数以释放分配的内存。

返回值

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

返回代码	说明
ERROR_INVALID_PARAMETER	一个或多个参数无效。
ERROR_NOT_ENOUGH_MEMORY	无法分配内存来创建聚合有效负载筛选器。

注解

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

TdhAggregatePayloadFilters 函数将单个提供程序的有效负载筛选器聚合到单个数据结构中，以便与 EnableTraceEx2 函数一起使用。 TdhAggregatePayloadFilters 为聚合有效负载筛选器分配和填充不透明数据结构。不再需要聚合有效负载筛选器时， TdhCleanupPayloadEventFilterDescriptor 函数用于释放为返回的EVENT_FILTER_DESCRIPTOR 结构中的聚合有效负载筛选器分配的内存。

示例

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

要求

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