Função TdhCreatePayloadFilter (tdh.h)
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 |
|---|---|
|
Os metadados do provedor não foram encontrados. |
|
Um ou mais dos parâmetros não são válidos. |
|
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. |
|
Não é possível alocar memória para criar o filtro de carga. |
|
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 |