Fonction EtwWriteEx (wdm.h)
La fonction EtwWriteEx est une fonction de suivi pour les événements de publication 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, 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
Identificateurs d’instance 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éfini sur zéro si vous ne prenez pas en charge les filtres ou si l’événement est écrit 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. Le ActivityID permet de regrouper les événements associés et est utilisé dans le suivi de bout en bout. Si la valeur EST NULL, ETW obtient l’identificateur 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é 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 de retour
Retourne ERROR_SUCCESS en cas de réussite ou d’une des valeurs suivantes lors de l’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 est incorporé dans le fournisseur. Le fournisseur doit donc être disponible pour qu’un consommateur consomme 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 de EtwWrite avec un appel à EtwEventEnabled ou EtwProviderEnabled.
Utilisez les paramètres ActivityId et RelatedActivityId lorsque vous souhaitez lier 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 effectuent un travail 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, quand IRQL est supérieur à APC_LEVEL, toutes les données transmises au EtwWrite, EtwWriteEx, EtwWriteString, Fonctions 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 au EtwWrite, EtwWriteEx, EtwWriteStringet fonctions EtwWriteTransfer doivent résider dans la mémoire de l’espace système, quel que soit l’irQL.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 7 |
| serveur minimum pris en charge | Windows Server 2008 R2 |
| plateforme cible | Universel |
| d’en-tête | wdm.h |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |