TdhAggregatePayloadFilters, fonction (tdh.h)

Article
03/02/2024

La fonction TdhAggregatePayloadFilters agrège plusieurs filtres de charge utile pour un seul fournisseur en une seule structure de données à utiliser avec la fonction EnableTraceEx2 .

Syntaxe

TDHSTATUS TdhAggregatePayloadFilters(
                 ULONG                    PayloadFilterCount,
                 PVOID                    *PayloadFilterPtrs,
  [in, optional] PBOOLEAN                 EventMatchALLFlags,
  [out]          PEVENT_FILTER_DESCRIPTOR EventFilterDescriptor
);

Paramètres

PayloadFilterCount

Nombre de filtres de charge utile.

PayloadFilterPtrs

Tableau de filtres uniques de charge utile d’événement, chacun créé par un appel à la fonction TdhCreatePayloadFilter .

[in, optional] EventMatchALLFlags

Tableau de valeurs booléennes qui correspondent à chaque filtre de charge utile passé dans le paramètre PayloadFilterPtrs et indique comment les événements sont gérés lorsque plusieurs conditions sont spécifiées. Ce paramètre affecte uniquement les situations où plusieurs filtres de charge utile sont spécifiés pour le même événement.

Quand une valeur booléenne 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. Si cet indicateur est défini sur TRUE sur un ou plusieurs filtres pour le même ID d’événement ou la même version d’événement, l’événement est écrit uniquement si tous les filtres marqués pour l’événement sont satisfaits.

Quand une valeur booléenne a la valeur FALSE, un événement est écrit dans une session uniquement si toutes les conditions spécifiées dans le filtre sont TRUE. Si cet indicateur a la valeur FALSE sur un ou plusieurs filtres pour le même ID d’événement ou la même version d’événement, l’événement est écrit si l’un des filtres sans indicateur est satisfait.

[out] EventFilterDescriptor

Pointeur vers une structure EVENT_FILTER_DESCRIPTOR à utiliser avec la fonction EnableTraceEx2 . La structure EVENT_FILTER_DESCRIPTOR contient un pointeur vers les filtres de charge utile agrégés, qui ont été alloués par cette fonction.

Lorsque l’appelant a terminé d’utiliser cette structure EVENT_FILTER_DESCRIPTOR avec la fonction EnableTraceEx2 , la fonction TdhCleanupPayloadEventFilterDescriptor 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_INVALID_PARAMETER	Un ou plusieurs paramètres ne sont pas valides.
ERROR_NOT_ENOUGH_MEMORY	Impossible d’allouer de la mémoire pour créer le filtre de charge utile agrégé.

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 TdhAggregatePayloadFilters agrège les filtres de charge utile d’un fournisseur unique en une seule structure de données à utiliser avec la fonction EnableTraceEx2 . TdhAggregatePayloadFilters alloue et remplit une structure de données opaque pour un filtre de charge utile agrégée. Lorsque le filtre de charge utile agrégée n’est plus nécessaire, la fonction TdhCleanupPayloadEventFilterDescriptor est utilisée pour libérer la mémoire allouée pour le filtre de charge utile agrégée dans la structure EVENT_FILTER_DESCRIPTOR retournée.

Exemples

Pour obtenir un exemple qui utilise la fonction TdhAggregatePayloadFilters pour agréger 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

Condition requise	Valeur
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