Функция TdhAggregatePayloadFilters (tdh.h)

Статья
03/02/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. Если этот флаг имеет значение TRUE для одного или нескольких фильтров для одного и того же идентификатора события или версии события, то событие записывается только в том случае, если все помеченные фильтры для события удовлетворены.

Если логическое значение равно FALSE, событие записывается в сеанс только в том случае, если все указанные в фильтре условия имеют значение TRUE. Если этот флаг имеет значение FALSE для одного или нескольких фильтров для одного и того же идентификатора события или версии события, то событие записывается, если выполняется какой-либо из фильтров, не помеченных.

[out] EventFilterDescriptor

Указатель на EVENT_FILTER_DESCRIPTOR структуру, используемую с функцией EnableTraceEx2 . Структура 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
Header	tdh.h
Библиотека	Tdh.lib
DLL	Tdh.dll