Fonction EtwWriteEx (wdm.h)
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 |