Fonction TraceLoggingRegister (traceloggingprovider.h)

Article
08/26/2023

Inscrit un fournisseur TraceLogging afin qu’il puisse être utilisé pour journaliser des événements. L’inscription est valide jusqu’à ce que le fournisseur ne soit pas inscrit ou que le processus se termine.

Syntaxe

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

Paramètres

hProvider

Handle du fournisseur TraceLogging à inscrire. Le handle ne doit pas déjà être inscrit.

Valeur retournée

Si vous appelez cette fonction à partir du code en mode utilisateur, la fonction retourne un HRESULT. Utilisez la SUCCEEDED() macro pour déterminer si la fonction réussit.

Si vous appelez cette fonction à partir de code en mode noyau, la fonction retourne un NTSTATUS. Utilisez la NT_SUCCESS() macro pour déterminer si la fonction réussit.

Notes

Le code d’erreur retourné par TraceLoggingRegister 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 TraceLoggingRegister.

Remarques

Lorsqu’un composant commence à s’exécuter, tout handle de fournisseur TraceLogging dans le composant est dans un état non enregistré et toute tentative d’utilisation du handle du fournisseur pour générer des événements est ignorée en mode silencieux. Avant que le fournisseur puisse écrire des événements, vous devez inscrire le fournisseur à l’aide de TraceLoggingRegister. Vous effectuez généralement cette opération lors du démarrage du composant, par exemple dans main, wmain, WinMain, DllMain(DLL_PROCESS_ATTACH)ou DriverEntry. À l’arrêt du composant, annulez l’inscription du fournisseur en appelant TraceLoggingUnregister.

N’appelez pas TraceLoggingRegister sur un handle de fournisseur déjà inscrit. Vous pouvez annuler l’inscription d’un handle, puis l’inscrire à nouveau si nécessaire, bien que l’inscription et la désinscription répétées du handle puissent entraîner des problèmes de performances et doivent être évitées (par exemple, ne pas inscrire, écrire quelques événements, puis annuler l’inscription ; au lieu de cela, inscrire une fois au démarrage du composant et annuler l’inscription à l’arrêt du composant).

TraceLoggingRegister n’est pas thread-safe en ce qui concerne d’autres appels à TraceLoggingRegister ou TraceLoggingUnregister sur le même handle. N’appelez pas TraceLoggingRegister s’il est possible qu’un autre thread appelle TraceLoggingRegister ou TraceLoggingUnregister sur le même handle en même temps.

En cas d’échec de TraceLoggingRegister , le handle du fournisseur reste non inscrit et toutes les utilisations du handle du fournisseur seront sans danger. En particulier, il est impossible d’appeler TraceLoggingWrite ou TraceLoggingUnregister avec un handle de fournisseur non inscrit.

Important

Si votre DLL ou votre pilote appelle TraceLoggingRegister sur un handle de fournisseur, il doit appeler TraceLoggingUnregister sur ce handle de fournisseur avant que la DLL ou le pilote ne se décharge. Si une DLL se décharge sans appeler TraceLoggingUnregister, le processus peut se bloquer par la suite. Si un pilote se décharge sans appeler TraceLoggingUnregister, le système peut se bloquer par la suite. La fonction TraceLoggingRegister établit un rappel de configuration ETW et TraceLoggingUnregister annule le rappel. Si le rappel n’est pas annulé et que le module se décharge, un incident se produit la prochaine fois qu’ETW essaie d’appeler le rappel.

Avertissement

Si votre pilote appelle TraceLoggingRegister et rencontre une erreur pendant DriverEntry, il doit appeler TraceLoggingUnregister avant de renvoyer l’erreur à partir de DriverEntry. Les routines de nettoyage normales des pilotes ne sont pas appelées si le pilote retourne une erreur à partir de DriverEntry, et si l’échec de l’appel de TraceLoggingUnregister entraîne le blocage du système.

TraceLoggingRegister effectue les opérations suivantes :

Appelle EventRegister pour ouvrir la connexion à ETW.
Si EventRegister réussit, appelez TraceLoggingSetInformation avec InformationClassEventProviderSetTraits pour configurer le fournisseur pour la prise en charge de TraceLogging.

Un appel à TraceLoggingRegister est identique à un appel à TraceLoggingRegisterEx avec NULL pour les paramètres de rappel et de contexte . Utilisez TraceLoggingRegisterEx si vous devez recevoir un rappel d’activation ETW lorsque les sessions activent ou désactivent votre fournisseur.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
En-tête	traceloggingprovider.h
Bibliothèque	Advapi32.lib