TdhCreatePayloadFilter, fonction (tdh.h)
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 |
|---|---|
|
Les métadonnées du fournisseur sont introuvables. |
|
Un ou plusieurs paramètres ne sont pas valides. |
|
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. |
|
Impossible d’allouer de la mémoire pour créer le filtre de charge utile. |
|
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 |