TdhCreatePayloadFilter, fonction (tdh.h)

Article
08/26/2023

La fonction TdhCreatePayloadFilter crée un filtre unique pour une charge utile unique à utiliser avec la fonction EnableTraceEx2 .

Syntaxe

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

Paramètres

[in] ProviderGuid

GUID qui identifie le fournisseur de manifeste du paramètre EventDescriptor .

[in] EventDescriptor

Pointeur vers le descripteur d’événements dont la charge utile sera filtrée.

[in] EventMatchANY

Valeur booléenne qui indique comment les événements sont gérés lorsque plusieurs conditions sont spécifiées.

Lorsque ce paramètre a la valeur TRUE, un événement est écrit dans une session si l’une des conditions spécifiées dans le filtre est TRUE.

Lorsque ce paramètre a la valeur FALSE, un événement est écrit dans une session uniquement si toutes les conditions spécifiées dans le filtre ont la valeur TRUE.

[in] PayloadPredicateCount

Nombre de conditions spécifiées dans le filtre. Cette valeur doit être inférieure ou égale à la constante ETW_MAX_PAYLOAD_PREDICATES définie dans le fichier d’en-tête Tdh.h .

[in] PayloadPredicates

Pointeur vers un tableau de structures PAYLOAD_FILTER_PREDICATE qui contiennent les conditions de liste spécifiées par le filtre.

[out] PayloadFilter

En cas de réussite, ce paramètre retourne un pointeur vers un filtre de charge utile unique qui est correctement dimensionné et généré pour les conditions spécifiées.

Lorsque l’appelant a terminé d’utiliser le filtre de charge utile retourné avec la fonction EnableTraceEx2 , la fonction TdhDeletePayloadFilter doit être appelée pour libérer la mémoire allouée.

Valeur retournée

Retourne ERROR_SUCCESS en cas de réussite. Sinon, cette fonction retourne l’un des codes de retour suivants en plus d’autres.

Code de retour	Description
ERROR_FILE_NOT_FOUND	Les métadonnées du fournisseur sont introuvables.
ERROR_INVALID_PARAMETER	Un ou plusieurs paramètres ne sont pas valides.
ERROR_INSUFFICIENT_BUFFER	Le filtre de charge utile résultant ne correspond pas à la limite de MAX_EVENT_FILTER_PAYLOAD_SIZE imposée par la fonction EnableTraceEx2 sur les structures EVENT_FILTER_DESCRIPTOR dans une charge utile.
ERROR_NOT_ENOUGH_MEMORY	Impossible d’allouer de la mémoire pour créer le filtre de charge utile.
ERROR_NOT_FOUND	Les informations de schéma pour le GUID du fournisseur fourni sont introuvables.

Remarques

Sur Windows 8.1,Windows Server 2012 R2 et versions ultérieures, les filtres de charge utile d’événement peuvent être utilisés par la fonction EnableTraceEx2 pour filtrer sur le contenu spécifique de l’événement dans une session d’enregistreur d’événements.

La fonction TdhCreatePayloadFilter permet de créer un filtre de charge utile unique pour une seule charge utile à utiliser avec la fonction EnableTraceEx2 . TdhCreatePayloadFilter alloue et remplit une structure de données opaque pour un filtre de charge utile unique. Lorsque le filtre de charge utile n’est plus nécessaire, la fonction TdhDeletePayloadFilter est utilisée pour libérer la mémoire allouée pour un filtre de charge utile.

Pour un seul fournisseur, plusieurs événements peuvent avoir des filtres de charge utile distincts. Il peut également y avoir plusieurs filtres pour le même événement, avec une charge utile passée à la session si l’un ou l’ensemble des filtres de l’événement la passent.

La fonction EnableTraceEx2 prend un tableau de structures EVENT_FILTER_DESCRIPTOR dans les structures ENABLE_TRACE_PARAMETERS passées dans le paramètre EnableParameters . Il ne peut y avoir qu’une seule entrée dans le tableau pour chaque type de filtre d’événement. La fonction TdhAggregatePayloadFilters peut être utilisée pour agréger une liste de filtres de charge utile pour un fournisseur unique créé à l’aide de TdhCreatePayloadFilter en une seule structure de données et retourner un EVENT_FILTER_DESCRIPTOR à utiliser avec la fonction EnableTraceEx2 .

Exemples

Pour obtenir un exemple qui utilise la fonction TdhCreatePayloadFilter pour créer des filtres de charge utile à utiliser dans le filtrage sur des conditions spécifiques dans une session d’enregistreur d’événements, consultez l’exemple de la fonction EnableTraceEx2 .

Configuration requise


Client minimal pris en charge	Windows 8.1 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	tdh.h
Bibliothèque	Tdh.lib
DLL	Tdh.dll