Функция 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

Идентификатор GUID, определяющий поставщика манифеста параметра EventDescriptor .

[in] EventDescriptor

Указатель на дескриптор события, полезные данные которого будут отфильтрованы.

[in] EventMatchANY

Логическое значение, указывающее, как обрабатываются события при указании нескольких условий.

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

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

[in] PayloadPredicateCount

Количество условий, указанных в фильтре. Это значение должно быть меньше или равно константы ETW_MAX_PAYLOAD_PREDICATES , определенной в файле заголовка Tdh.h .

[in] PayloadPredicates

Указатель на массив PAYLOAD_FILTER_PREDICATE структур, содержащих условия списка, заданные фильтром.

[out] PayloadFilter

При успешном выполнении этот параметр возвращает указатель на один фильтр полезных данных, который имеет правильный размер и создан для указанных условий.

Когда вызывающий объект завершает работу с использованием возвращенного фильтра полезных данных с функцией EnableTraceEx2 , необходимо вызвать функцию TdhDeletePayloadFilter , чтобы освободить выделенную память.

Возвращаемое значение

В случае успешного выполнения возвращает ERROR_SUCCESS. В противном случае эта функция возвращает один из следующих кодов возврата в дополнение к другим.

Код возврата	Описание
ERROR_FILE_NOT_FOUND	Метаданные для поставщика не найдены.
ERROR_INVALID_PARAMETER	Один или несколько параметров недопустимы.
ERROR_INSUFFICIENT_BUFFER	Результирующий фильтр полезных данных не будет соответствовать ограничению MAX_EVENT_FILTER_PAYLOAD_SIZE , налагаемого функцией EnableTraceEx2 на структуры EVENT_FILTER_DESCRIPTOR полезных данных.
ERROR_NOT_ENOUGH_MEMORY	Не удалось выделить память для создания фильтра полезных данных.
ERROR_NOT_FOUND	Сведения о схеме для предоставленного GUID поставщика не найдены.

В Windows 8.1, Windows Server 2012 R2 и более поздних версий функции EnableTraceEx2 может использовать фильтры полезных данных событий для фильтрации по определенному содержимому события в сеансе средства ведения журнала.

Функция TdhCreatePayloadFilter используется для создания одного фильтра полезных данных для одной полезной нагрузки, которая будет использоваться с функцией EnableTraceEx2 . TdhCreatePayloadFilter выделяет и заполняет непрозрачную структуру данных для одного фильтра полезных данных. Если фильтр полезных данных больше не нужен, функция TdhDeletePayloadFilter используется для освобождения памяти, выделенной для фильтра полезных данных.

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

Функция EnableTraceEx2 принимает массив EVENT_FILTER_DESCRIPTOR структур в структурах ENABLE_TRACE_PARAMETERS , передаваемых в параметре EnableParameters . Для каждого типа фильтра событий в массиве может быть только одна запись. Функцию TdhAggregatePayloadFilters можно использовать для агрегирования списка фильтров полезных данных для одного поставщика, созданного с помощью TdhCreatePayloadFilter , в одну структуру данных и возврата EVENT_FILTER_DESCRIPTOR для использования с функцией EnableTraceEx2 .

Примеры

Пример использования функции TdhCreatePayloadFilter для создания фильтров полезных данных для фильтрации по определенным условиям в сеансе средства ведения журнала см. в примере функции EnableTraceEx2 .

Требования


Минимальная версия клиента	Windows 8.1 [только классические приложения]
Минимальная версия сервера	Windows Server 2012 R2 [только классические приложения]
Целевая платформа	Windows
Header	tdh.h
Библиотека	Tdh.lib
DLL	Tdh.dll