Fonction EtwWrite (wdm.h)
La fonction EtwWrite est une fonction de suivi pour la publication d’événements dans votre code de pilote en mode noyau.
Syntaxe
NTSTATUS EtwWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[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, 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.
[in] UserDataCount
Nombre de structures EVENT_DATA_DESCRIPTOR dans UserData.
[in, optional] UserData
Pointeur vers le tableau de structures EVENT_DATA_DESCRIPTOR.
Valeur retournée
Si l’événement a été publié, EtwWrite retourne STATUS_SUCCESS.
Si le pointeur vers le handle d’inscription du fournisseur d’événements n’est pas valide, EtwWrite retourne STATUS_INVALID_HANDLE. Le fournisseur d’événements doit être inscrit avant l’appel d’EtwWrite . EtwWrite peut également retourner STATUS_INVALID_HANDLE s’il ne parvient pas à consigner l’événement.
Si le nombre de structures EVENT_DATA_DESCRIPTOR spécifiées dans UserDataCount est supérieur au nombre maximal autorisé (128), EtwWrite retourne STATUS_INVALID_PARAMETER.
Si ActivityID est spécifié, mais que la mémoire disponible est insuffisante pour consigner les données associées à l’événement, EtwWrite retourne STATUS_NO_MEMORY.
Si le fournisseur n’est activé pour aucune session, EtwWrite retourne STATUS_SUCCESS et les événements ne sont pas consignés.
Les événements peuvent être perdus pour plusieurs raisons ; par exemple, si le taux d’événements est trop élevé ou si la taille de l’événement est supérieure à la taille de la mémoire tampon. Dans ce cas, le compteur EventsLost , membre de la structure EVENT_TRACE_PROPERTIES de l’enregistreur d’événements correspondant, est mis à jour avec le nombre d’événements qui n’ont pas été enregistrés.
Remarques
La fonction EtwWrite est l’équivalent en mode noyau de la fonction EventWrite en mode utilisateur. 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.
Avant d’appeler la fonction EtwWrite pour publier un événement, vous devez inscrire le fournisseur auprès d’EtwRegister. 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 .
Si vous utilisez le paramètre UserData facultatif dans la fonction EtwWrite pour consigner des données d’événement supplémentaires, vous pouvez utiliser la macro EventDataDescCreate pour simplifier la création des structures EVENT_DATA_DESCRIPTOR. L’exemple suivant utilise la macro EventDataDescCreate pour initialiser EVENT_DATA_DESCRIPTOR structures avec le nom de l’appareil et son status. La macro EventDataDescCreate stocke les pointeurs vers les données (autrement dit, elle ne stocke pas de copies des données). Les pointeurs doivent rester valides jusqu’à ce que l’appel à EtwWrite soit retourné.
Vous pouvez appeler EtwWrite à 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.
Exemple
//
// Register the provider with ETW in DriverEntry
// Unregister the provider in DriverUnload
//
// Build the EVENT_DATA_DESCRIPTOR structures using
// the EventDataDescCreate macros
if (RegHandle != (REGHANDLE)NULL) {
//
// Log an Event with : DeviceNameLength
// DeviceName
// Status
//
EventDataDescCreate(&EventDataDescriptor[0],
(PVOID)&DeviceName.Length,
sizeof(USHORT));
EventDataDescCreate(&EventDataDescriptor[1],
(PVOID)DeviceName.Buffer,
DeviceName.Length);
EventDataDescCreate(&EventDataDescriptor[2],
(PVOID)&Status,
sizeof(ULONG));
EtwWrite(RegHandle, // Handle from EtwRegister
&StartEvent, // EventDescriptor
NULL, // Activity ID
3, // Number of data items
EventDataDescriptor); // Array of data descriptors
}
//
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| En-tête | wdm.h (inclure Wdm.h, Ntddk.h) |
| Bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | N’importe quel niveau (voir la section Commentaires).) |