Fonction EtwRegister (wdm.h)

Article
02/27/2024

La fonction EtwRegister inscrit le fournisseur d’événements et doit être appelée avant qu’un fournisseur puisse commencer le suivi. La fonction EtwRegister est l’équivalent en mode noyau de la fonction EventRegister en mode utilisateur. La fonction peut également fournir un pointeur vers une fonction de rappel facultative qui peut être utilisée pour fournir des fonctionnalités de filtrage d’événements supplémentaires.

Syntaxe

NTSTATUS EtwRegister(
  [in]           LPCGUID            ProviderId,
  [in, optional] PETWENABLECALLBACK EnableCallback,
  [in, optional] PVOID              CallbackContext,
  [out]          PREGHANDLE         RegHandle
);

Paramètres

[in] ProviderId

Pointeur vers le GUID du fournisseur d’événements.

[in, optional] EnableCallback

Pointeur vers une fonction de rappel facultative. La fonction de rappel fournit des fonctionnalités de filtrage d’événements supplémentaires. La fonction de rappel est définie par l’utilisateur.

[in, optional] CallbackContext

La fonction renvoie le contexte de rappel facultatif lorsqu’un rappel est effectué. Vous pouvez spécifier le contexte facultatif lorsque vous inscrivez un fournisseur. Le paramètre CallbackContext prend en charge les scénarios dans lesquels un rappel est partagé par plusieurs fournisseurs, comme dans une classe C++. CallbackContext permet de distinguer les instances de fournisseur cible pour l’activation du rappel.

[out] RegHandle

Pointeur vers une variable qui reçoit le handle d’inscription du fournisseur si l’appel de fonction réussit.

Valeur retournée

La fonction EtwRegister retourne un code status à partir de la liste suivante :

Code de retour	Description
STATUS_SUCCESS	Indique que le fournisseur d’événements a été correctement inscrit auprès d’ETW.
STATUS_INVALID_PARAMETER	Indique que le paramètre n’était pas valide.
STATUS_Xxx	Indique que la demande a échoué pour la raison spécifiée par la valeur NTSTATUS. Consultez Ntstatus.h pour plus d’informations sur le code de retour status réel.

Remarques

Avant qu’un pilote en mode noyau puisse suivre les événements, le pilote doit s’inscrire en tant que fournisseur d’événements à l’aide de la fonction EtwRegister . Lorsqu’un pilote en mode noyau appelle EtwRegister, la fonction retourne un handle d’inscription. Ce handle d’inscription peut être utilisé pour tester si un mot clé ou un niveau est activé pour un fournisseur spécifique et pour appeler des fonctions de suivi d’événements et de journalisation. Une fois le suivi terminé, un pilote doit appeler la fonction EtwUnregister pour annuler l’inscription du fournisseur. Pour chaque appel à EtwRegister , il doit y avoir un appel correspondant à EtwUnregister. L’échec de l’inscription du fournisseur d’événements peut entraîner des erreurs lorsque le processus est déchargé, car les fonctions de rappel associées au processus ne sont plus valides. Aucun appel de suivi ne doit être effectué en dehors du code délimité par les fonctions EtwRegister et EtwUnregister . Pour de meilleures performances, vous pouvez appeler la fonction EtwRegister dans votre routine DriverEntry et la fonction EtwUnregister dans votre routine DriverUnload .

Les appelants d’EtwRegister doivent être en cours d’exécution à IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et les versions plus récentes de Windows.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm)

Voir aussi

EtwUnregister

Partager via