Fonction EventRegister (evntprov.h)

Inscrit un fournisseur d’événements ETW, créant un handle qui peut être utilisé pour écrire des événements ETW.

Syntaxe

ULONG EVNTAPI EventRegister(
  [in]           LPCGUID         ProviderId,
  [in, optional] PENABLECALLBACK EnableCallback,
  [in, optional] PVOID           CallbackContext,
  [out]          PREGHANDLE      RegHandle
);

Paramètres

[in] ProviderId

GUID qui identifie de manière unique le fournisseur, parfois appelé GUID de contrôle. Il doit s’agir d’un identificateur stable afin que les contrôleurs de suivi puissent utiliser le GUID pour s’abonner aux événements de ce fournisseur.

[in, optional] EnableCallback

Option EnableCallback appelée par ETW lorsqu’une session de trace active ou désactive ce fournisseur. Utilisez NULL si aucun rappel n’est nécessaire.

[in, optional] CallbackContext

Données de contexte facultatives que ETW fournira lors de l’appel d’EnableCallback. Utilisez NULL si aucun contexte de rappel n’est nécessaire.

[out] RegHandle

Reçoit le handle d’inscription du fournisseur d’événements. Le handle est utilisé dans les appels suivants aux API de fournisseur telles que EventWrite, EventProviderEnabled et EventRegister.

Avant que votre fournisseur ne décharge ou se quitte, libérez le handle d’inscription du fournisseur en appelant EventUnregister. Une DLL qui décharge sans libérer tous les handles de fournisseur qu’elle a enregistrés peut provoquer le blocage du processus.

Valeur retournée

Retourne ERROR_SUCCESS en cas de réussite.

Le code d’erreur retourné par EventRegister est principalement destiné à être utilisé dans les scénarios de débogage et de diagnostic. La plupart du code de production doit continuer à s’exécuter même si un fournisseur ETW n’a pas pu s’inscrire. Par conséquent, les builds de version doivent généralement ignorer le code d’erreur retourné par EventRegister.

Notes

EventRegister crée un handle que vous pouvez utiliser pour écrire des événements ETW via EventWrite, EventWriteTransfer ou EventWriteEx.

L’inscription d’un fournisseur d’événements ne doit pas être confondue avec l’installation du manifeste d’un fournisseur d’événements.

• L’API EventRegister effectue l’inscription d’un fournisseur d’événements pour créer un handle de fournisseur. Il s’agit d’une opération d’étendue de processus (le handle est valide uniquement dans le processus). Le handle peut être utilisé pour écrire des événements ETW. Tous les événements écrits à l’aide du handle seront marqués avec le ProviderId qui a été spécifié lors de l’inscription du fournisseur. Il n’est pas nécessaire d’installer un manifeste pour écrire des événements ou capturer des traces (bien que l’installation du manifeste puisse être nécessaire pour décoder les événements du fournisseur ou pour que le fournisseur fonctionne avec le journal des événements).
• L’outilwevtutil.exe est utilisé pour installer ou désinstaller le manifeste d’un fournisseur d’événements. L’installation d’un manifeste de fournisseur d’événements signifie que les informations du manifeste sont enregistrées sur le système. Les informations enregistrées sont globales sur le système et sont conservées jusqu’à ce que le manifeste soit désinstallé. Les informations enregistrées incluent les noms, LES GUID, les canaux et les chemins d’accès DLL de ressources des fournisseurs définis dans le manifeste. Les informations du manifeste sont utilisées par les outils de décodage de trace et le journal des événements.

La plupart des composants inscrivent leur fournisseur d’événements lors de l’initialisation du composant et annulent l’inscription de leur fournisseur d’événements à l’arrêt du composant. Par exemple, une application (EXE) peut s’inscrire au démarrage de l’application et annuler l’inscription lors de la sortie de l’application. Une bibliothèque dynamique (DLL) peut s’inscrire DllMain pendant l’attachement de processus et peut se désinscrire DllMain pendant le détachement du processus.

Étant donné que le suivi d’événements est un problème de débogage/diagnostic et n’est normalement pas une fonctionnalité critique pour l’application, la plupart des applications de vente au détail doivent ignorer en mode silencieux les échecs retournés par EventRegister. En cas d’échec, EventRegister définit le paramètre RegHandle sur zéro afin que les utilisations ultérieures du RegHandle (par exemple, dans les appels à EventWrite et EventUnregister) n’aient aucun effet.

Chaque processus peut inscrire jusqu’à 1 024 fournisseurs. Toutefois, vous devez limiter le nombre de fournisseurs inscrits par votre composant à un ou deux. Cette limite inclut les fournisseurs inscrits à l’aide de cette fonction et les fournisseurs inscrits à l’aide de RegisterTraceGuids.

Avant Windows Vista : Il n’existe aucune limite spécifique au nombre de fournisseurs qu’un processus peut inscrire.

Spécifications

Voir aussi

EnableCallback

EventWrite

EventUnregister