Função TdhCreatePayloadFilter (tdh.h)

Artigo
08/26/2023

A função TdhCreatePayloadFilter cria um único filtro para uma única carga a ser usada com a função EnableTraceEx2 .

Sintaxe

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

Parâmetros

[in] ProviderGuid

Um GUID que identifica o provedor de manifesto do parâmetro EventDescriptor .

[in] EventDescriptor

Um ponteiro para o descritor de eventos cuja carga será filtrada.

[in] EventMatchANY

Um valor booliano que indica como os eventos são tratados quando várias condições são especificadas.

Quando esse parâmetro for TRUE, um evento será gravado em uma sessão se qualquer uma das condições especificadas especificadas no filtro for TRUE.

Quando esse parâmetro for FALSE, um evento será gravado em uma sessão somente se todas as condições especificadas especificadas no filtro forem TRUE.

[in] PayloadPredicateCount

O número de condições especificadas no filtro. Esse valor deve ser menor ou igual à constante ETW_MAX_PAYLOAD_PREDICATES definida no arquivo de cabeçalho Tdh.h .

[in] PayloadPredicates

Um ponteiro para uma matriz de estruturas de PAYLOAD_FILTER_PREDICATE que contêm as condições de lista especificadas pelo filtro.

[out] PayloadFilter

Com êxito, esse parâmetro retorna um ponteiro para um único filtro de carga que é dimensionado corretamente e criado para as condições especificadas.

Quando o chamador terminar de usar o filtro de carga retornado com a função EnableTraceEx2 , a função TdhDeletePayloadFilter deverá ser chamada para liberar a memória alocada.

Valor retornado

Retorna ERROR_SUCCESS se tiver êxito. Caso contrário, essa função retornará um dos seguintes códigos de retorno, além de outros.

Código de retorno	Descrição
ERROR_FILE_NOT_FOUND	Os metadados do provedor não foram encontrados.
ERROR_INVALID_PARAMETER	Um ou mais dos parâmetros não são válidos.
ERROR_INSUFFICIENT_BUFFER	O filtro de conteúdo resultante não caberia no limite de MAX_EVENT_FILTER_PAYLOAD_SIZE imposto pela função EnableTraceEx2 nas estruturas de EVENT_FILTER_DESCRIPTOR em uma carga.
ERROR_NOT_ENOUGH_MEMORY	Não é possível alocar memória para criar o filtro de carga.
ERROR_NOT_FOUND	As informações de esquema do GUID do provedor fornecido não foram encontradas.

Comentários

Em Windows 8.1, Windows Server 2012 R2 e posterior, filtros de conteúdo de evento podem ser usados pela função EnableTraceEx2 para filtrar o conteúdo específico do evento em uma sessão de agente.

A função TdhCreatePayloadFilter é usada para criar um único filtro de carga para uma única carga a ser usada com a função EnableTraceEx2 . O TdhCreatePayloadFilter aloca e preenche uma estrutura de dados opaca para um único filtro de carga. Quando o filtro de carga não é mais necessário, a função TdhDeletePayloadFilter é usada para liberar memória alocada para um filtro de carga.

Para um único provedor, vários eventos podem ter filtros de conteúdo distintos. Também pode haver vários filtros para o mesmo evento, com uma carga sendo passada para a sessão se algum ou todos os filtros do evento passarem por ele.

A função EnableTraceEx2 usa uma matriz de estruturas EVENT_FILTER_DESCRIPTOR nas estruturas ENABLE_TRACE_PARAMETERS passadas no parâmetro EnableParameters . Só pode haver uma entrada na matriz para cada tipo de filtro de evento. A função TdhAggregatePayloadFilters pode ser usada para agregar uma lista de filtros de carga para um único provedor criado usando o TdhCreatePayloadFilter em uma única estrutura de dados e retornar um EVENT_FILTER_DESCRIPTOR para uso com a função EnableTraceEx2 .

Exemplos

Para obter um exemplo que usa a função TdhCreatePayloadFilter para criar filtros de conteúdo a serem usados na filtragem em condições específicas em uma sessão de agente, consulte o exemplo da função EnableTraceEx2 .

Requisitos


Cliente mínimo com suporte	Windows 8.1 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	tdh.h
Biblioteca	Tdh.lib
DLL	Tdh.dll