Fonction EtwWriteEx (wdm.h)

  • Article

La fonction EtwWriteEx est une fonction de suivi pour la publication d’événements qui prennent en charge le filtrage dans votre code de pilote en mode noyau.

Syntaxe

NTSTATUS EtwWriteEx(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG64                Filter,
  [in]           ULONG                  Flags,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Paramètres

[in] RegHandle

Pointeur vers le handle d’inscription du fournisseur d’événements, qui est retourné par la fonction EtwRegister si l’inscription du fournisseur d’événements réussit.

[in] EventDescriptor

Pointeur vers la structure EVENT_DESCRIPTOR .

[in] Filter

Le instance identificateurs qui identifient la session dans laquelle l’événement n’est pas écrit. Autrement dit, la valeur est un masque de sessions qui doivent être exclues de la journalisation (filtrées). Utilisez une or au niveau du bit pour spécifier plusieurs identificateurs. Définissez sur zéro si vous ne prenez pas en charge les filtres ou si l’événement est en cours d’écriture dans toutes les sessions (aucun filtre n’a échoué). Pour plus d’informations sur l’obtention de l’identificateur d’une session, consultez le paramètre FilterData de votre rappel EtwEnableCallback .

[in] Flags

Réservé. Doit être égal à zéro (0).

[in, optional] ActivityId

Identificateur qui indique l’activité associée à l’événement. L’Id d’activité permet de regrouper des événements connexes et est utilisé dans le suivi de bout en bout. Si la valeur est NULL, ETW obtient l’identificateur à partir du stockage local du thread. Pour plus d’informations sur l’obtention de cet identificateur, consultez EtwActivityIdControl.

[in, optional] RelatedActivityId

Identificateur d'activité du composant précédent. Utilisez ce paramètre pour lier les événements de votre composant aux événements du composant précédent. Pour obtenir l’identificateur d’activité qui a été défini pour le composant précédent, consultez les descriptions du paramètre ControlCode de la fonction EtwActivityIdControl .

[in] UserDataCount

Nombre de structures EVENT_DATA_DESCRIPTOR dans UserData. Le nombre maximal est 128.

[in, optional] UserData

Pointeur vers le tableau de structures EVENT_DATA_DESCRIPTOR. Définissez ce paramètre sur NULL si UserDataCount est égal à zéro. Les données doivent être dans l'ordre spécifié dans le manifeste.

Valeur retournée

Retourne ERROR_SUCCESS en cas de réussite ou l’une des valeurs suivantes en cas d’erreur.

Remarques

La fonction EtwWriteEx est l’équivalent en mode noyau de la fonction EventWriteEx en mode utilisateur. Les données d’événement écrites avec cette fonction nécessitent un manifeste. Le manifeste étant incorporé dans le fournisseur, celui-ci doit être disponible pour qu’un consommateur puisse consommer les données. Pour vous assurer qu’il existe un consommateur pour l’événement que vous publiez, vous pouvez précéder l’appel à EtwWrite par un appel à EtwEventEnabled ou EtwProviderEnabled.

Utilisez les paramètres ActivityId et RelatedActivityId lorsque vous souhaitez associer des événements dans différents composants dans un scénario de suivi de bout en bout. Par exemple, les composants A, B et C travaillent sur une activité associée et souhaitent lier leurs événements afin qu’un consommateur puisse consommer tous les événements liés à cette activité.

Vous pouvez appeler EtwWriteEx à n’importe quel IRQL. Toutefois, lorsque l’IRQL est supérieur à APC_LEVEL, les données transmises aux fonctions EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer ne doivent pas être paginables. Autrement dit, toute routine en mode noyau qui s’exécute à IRQL supérieure à APC_LEVEL ne peut pas accéder à la mémoire paginable. Les données transmises aux fonctions EtwWrite, EtwWriteEx, EtwWriteString et EtwWriteTransfer doivent résider dans la mémoire de l’espace système, quel que soit l’IRQL.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 7
Serveur minimal pris en charge Windows Server 2008 R2
Plateforme cible Universal
En-tête wdm.h
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe

Voir aussi

EtwWrite

EventWrite

EventWriteEx