Fonction de rappel PENABLECALLBACK (evntprov.h)

Les fournisseurs d’événements ETW définissent éventuellement une fonction EnableCallback pour recevoir des notifications de modification de configuration. Le type PENABLECALLBACK définit un pointeur vers cette fonction de rappel. EnableCallback est un espace réservé pour le nom de fonction défini par l’application.

Syntaxe

PENABLECALLBACK Penablecallback;

void Penablecallback(
  [in]           LPCGUID SourceId,
  [in]           ULONG IsEnabled,
  [in]           UCHAR Level,
  [in]           ULONGLONG MatchAnyKeyword,
                 ULONGLONG MatchAllKeyword,
  [in, optional] PEVENT_FILTER_DESCRIPTOR FilterData,
  [in, optional] PVOID CallbackContext
)
{...}

Paramètres

[in] SourceId

GUID spécifié par l’appelant qui active ou désactive le fournisseur.

La valeur provient du paramètre SourceIdd’EnableTraceEx ou du champ SourceId du ENABLE_TRACE_PARAMETERS passé à EnableTraceEx2.

Notes

SourceId est la valeur de la session spécifiée dans l’appel à l’API EnableTraceEx ou EnableTraceEx2. Il peut ou non être identique au GUID de la session.

SourceId sera défini sur GUID_NULL dans plusieurs scénarios où la notification n’a pas d’identificateur source. Par exemple, cela peut se produire lorsqu’une session de suivi a activé le fournisseur avant le démarrage du fournisseur, lorsque le fournisseur s’arrête ou lorsqu’un contrôleur de trace appelle une API EnableTrace sans spécifier de SourceId.

[in] IsEnabled

Indique le ControlCode correspondant à cette notification. Il peut s’agir de l’une des valeurs suivantes :

Valeur	Signification
EVENT_CONTROL_CODE_DISABLE_PROVIDER (0)	Aucune session n’a activé le fournisseur.
EVENT_CONTROL_CODE_ENABLE_PROVIDER (1)	Une ou plusieurs sessions ont activé le fournisseur.
EVENT_CONTROL_CODE_CAPTURE_STATE (2)	Une session demande au fournisseur de consigner ses informations d’état. Le fournisseur répond généralement en écrivant des événements contenant l’état du fournisseur.

Notes

La valeur de IsEnabled peut ne pas être identique à celle du ControlCode passé à l’API EnableTrace qui a déclenché cet événement. Par exemple, si deux sessions ont activé ce fournisseur et qu’une session désactive ce fournisseur en appelant EnableTraceEx2(..., EVENT_CONTROL_CODE_DISABLE_PROVIDER, ...), le fournisseur reçoit une notification avec IsEnabled défini sur EVENT_CONTROL_CODE_ENABLE_PROVIDER , car le fournisseur est toujours activé par l’autre session.

Après avoir reçu une notification DISABLE_PROVIDER , un fournisseur peut optimiser ses performances en désactivant tous les événements. Après avoir reçu une notification ENABLE_PROVIDER , un fournisseur doit activer l’écriture d’événements. Il peut également optimiser ses performances en enregistrant les valeurs des filtres Level, MatchAnyKeyword et MatchAllKeyword, puis en écrivant uniquement les événements qui passent les filtres (comme décrit dans les remarques). Après avoir reçu une notification de CAPTURE_STATE , un fournisseur peut prendre toutes les mesures qui semblent appropriées, en écrivant généralement des événements qui décrivent la configuration ou l’état du composant.

Un fournisseur doit ignorer les notifications avec des valeurs IsEnabled qu’il ne reconnaît ni ne prend pas en charge.

[in] Level

Valeur qui spécifie le détail des événements que le fournisseur doit écrire. Lorsqu’il est appelé avec le code de contrôle EVENT_CONTROL_CODE_ENABLE_PROVIDER, le fournisseur doit enregistrer la valeur Level et doit ensuite ignorer les événements où le niveau de détail de l’événement est supérieur au niveau enregistré, c’est-à-dire qu’un événement ne doit être écrit que si

eventDescriptor.Level <= recorded.Level

Le niveau dans la notification correspond au maximum des niveaux spécifiés par les contrôleurs de trace dans les appels à EnableTrace, EnableTraceEx ou EnableTraceEx2 à l’aide du GUID de ce fournisseur d’événements. En d’autres termes, si plusieurs sessions enregistrent des événements de ce fournisseur d’événements à différents niveaux de détail, le paramètre Level de la notification EnableCallback est défini sur le niveau le plus élevé (le plus détaillé) des niveaux.

[in] MatchAnyKeyword

Valeur de masque de bits qui spécifie les catégories d’événements que le fournisseur doit écrire. Lorsqu’il est appelé avec le code de contrôle EVENT_CONTROL_CODE_ENABLE_PROVIDER, le fournisseur doit enregistrer la valeur MatchAnyKeyword et doit ensuite ignorer les événements où le mot clé de l’événement est différent de zéro et n’a aucun des bits de l’élément MatchAnyKeyword enregistré, c’est-à-dire qu’un événement ne doit être écrit que si

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAnyKeyword) != 0

Le mot matchAnyKeyword dans la notification est l’union (OR) des mots clés de correspondance (activer les indicateurs) spécifiés par les contrôleurs de trace dans les appels à EnableTrace, EnableTraceEx et EnableTraceEx2 pour le GUID de ce fournisseur d’événements. En d’autres termes, si plusieurs sessions enregistrent des événements à partir de ce fournisseur d’événements avec différents filtres de correspondance mot clé, le paramètre MatchAnyKeyword pour la notification EnableCallback est défini sur le bit desOR filtres match-any-mot clé des sessions.

MatchAllKeyword

Valeur de masque de bits qui spécifie les catégories d’événements que le fournisseur doit écrire. En cas de notification avec le code de contrôle EVENT_CONTROL_CODE_ENABLE_PROVIDER, le fournisseur doit enregistrer la valeur MatchAllKeyword et doit ensuite ignorer les événements où le mot clé de l’événement est différent de zéro et n’a pas tous les bits de l’élément MatchAllKeyword enregistré, c’est-à-dire qu’un événement ne doit être écrit que si

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAllKeyword) == recorded.MatchAllKeyword

MatchAllKeyword dans la notification est la disjonction (AND) des mots clés de correspondance spécifiés par les contrôleurs de trace dans les appels à EnableTraceEx et EnableTraceEx2 pour le GUID de ce fournisseur d’événements. En d’autres termes, si plusieurs sessions enregistrent des événements à partir de ce fournisseur d’événements avec différents filtres match-all-mot clé, le paramètre MatchAllKeyword pour la notification EnableCallback est défini sur le bit desAND filtres match-all-mot clé des sessions.

[in, optional] FilterData

Pointeur vers un EVENT_FILTER_DESCRIPTOR avec des données de filtre pour le fournisseur d’événements.

Chaque session ne peut spécifier qu’un seul filtre. Le descripteur de filtre dans la notification de rappel contient un filtre de chaque session qui a spécifié des données de filtre lors de l’activation du fournisseur.

Les données de filtre sont valides uniquement dans le rappel. Les fournisseurs doivent effectuer une copie locale des données si les données sont nécessaires après le retour du rappel.

[in, optional] CallbackContext

Contexte du rappel. Il s’agit de la valeur du paramètre CallbackContext qui a été utilisé lorsque le fournisseur d’événements appelé EventRegister.

Valeur de retour

None

Notes

Les fournisseurs d’événements ETW qui ont besoin de notifications de modification de configuration doivent fournir un pointeur vers leur implémentation EnableCallback lorsqu’ils s’inscrivent via EventRegister. ETW appelle la fonction EnableCallback du fournisseur lorsqu’une modification est apportée à la configuration d’une session de trace impliquant le fournisseur. Par exemple, lorsqu’un contrôleur de session de suivi configure une trace via EnableTraceEx2 ou arrête une trace via ControlTrace, ETW appelle la fonction EnableCallback du fournisseur avec la configuration mise à jour résultante.

Notes

La plupart des fournisseurs d’événements n’implémentent pas EnableCallback directement. Au lieu de cela, la plupart des fournisseurs d’événements sont implémentés à l’aide d’une infrastructure ETW qui fournit sa propre implémentation EnableCallback et encapsule les appels à EventRegister, EventWrite et EventUnregister. Par exemple, vous pouvez écrire un manifeste d’événement , puis utiliser le compilateur de messages pour générer du code C/C++ pour les événements, ou vous pouvez utiliser TraceLogging pour éviter d’avoir besoin d’un manifeste. L’infrastructure ETW implémente généralement une fonction EnableCallback qui enregistre les valeurs , MatchAnyKeywordet de MatchAllKeywordLevella notification, et l’infrastructure utilise automatiquement les valeurs enregistrées pour filtrer les événements. L’infrastructure ETW prend généralement en charge l’appel d’un rappel fourni par l’utilisateur si l’utilisateur a besoin d’une gestion des notifications personnalisée. Par exemple, TraceLoggingProvider.h permet de spécifier un rappel de notification via TraceLoggingRegisterEx.

Important

La fonction EnableCallback du fournisseur doit être aussi simple que possible. Il doit enregistrer les informations requises et les retourner rapidement. Une fonction de rappel de longue durée peut entraîner des retards dans les API de contrôle de session ETW telles que EnableTraceEx2 ou ControlTrace. La fonction de rappel ne doit pas faire quoi que ce soit qui nécessite le verrou du chargeur du processus, c’est-à-dire qu’elle ne doit pas appeler directement ou indirectement LoadLibrary ou FreeLibrary. La fonction de rappel ne doit pas bloquer sur les verrous. La fonction de rappel peut provoquer un interblocage si elle bloque sur les verrous ou si elle appelle des API de contrôle de session ETW telles que StartTrace, ControlTrace ou EnableTrace.

Le rappel de notification permet au fournisseur d’événements de s’exécuter plus efficacement, car il peut effectuer son propre suivi du niveau, des mots clés et d’autres filtres. En suivant les filtres, le fournisseur peut ignorer efficacement les événements qui ne sont pas activés (c’est-à-dire, le fournisseur n’a pas besoin de préparer les données d’événement ou d’appeler EventWrite pour les événements qui ne sont pas nécessaires par les sessions de suivi).

Notez que le suivi des filtres n’est pas nécessaire pour le bon fonctionnement d’un fournisseur : ETW fournit des fonctions EventEnabled et EventProviderEnabled qu’un fournisseur peut utiliser, et les API EventWrite IGNOREnt en mode silencieux tous les événements désactivés. Toutefois, le suivi des filtres implémenté par le fournisseur peut être plus efficace que les appels à EventEnabled ou EventProviderEnabled.

Le rappel de notification permet également au fournisseur de gérer les demandes d’état de capture provenant des sessions de trace. Les demandes d’état de capture sont généralement envoyées par une session de trace lorsqu’elle commence à enregistrer des événements à partir d’un fournisseur. Si l’état de capture est pris en charge par un fournisseur, il peut répondre à la demande d’état de capture en journalisant les informations d’état, par exemple des informations de configuration ou des statistiques récapitulatives concernant l’opération du composant avant la demande.

La valeur level que ETW transmet au rappel est la valeur de niveau la plus élevée (la plus détaillée) spécifiée pour ce fournisseur d’événements par toute session de trace en cours d’exécution. Par exemple, si la session A a activé ce fournisseur pour les événements d’avertissement (niveau 3) et que la session B active le fournisseur pour les événements critiques (niveau 1), la valeur Niveau pour le rappel sera 3, et non 1.

De même, les valeurs MatchAnyKeyword et MatchAllKeyword sont des valeurs composites calculées à partir de la configuration de toutes les sessions qui ont activé le fournisseur d’événements. MatchAnyKeyword est le OR des paramètres EnableFlags/MatchAnyKeyword des sessions. MatchAllKeyword est le AND des paramètres MatchAllKeyword des sessions.

Si la fonction EnableCallback du fournisseur a capturé l’état Enabled, Level, MatchAnyKeyword et MatchAllKeyword du fournisseur, le fournisseur peut déterminer si un événement doit être écrit à l’aide d’une fonction comme suit :

BOOL MyProviderEventEnabled(
    _In_ const MY_PROVIDER_STATE* pProvider,
    _In_ const EVENT_DESCRIPTOR* pEvent)
{
    return
        pProvider->Enabled &&
        pEvent->Level <= pProvider->Level &&
        (pEvent->Keyword == 0 || (
            (pEvent->Keyword & pProvider->MatchAnyKeyword) != 0 &&
            (pEvent->Keyword & pProvider->MatchAllKeyword) == pProvider->MatchAllKeyword
        ));
}

Spécifications

Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	evntprov.h

Voir aussi

EventRegister

EnableTrace

EnableTraceEx2