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

Voir aussi

EtwEventEnabled

EtwProviderEnabled

EtwRegister

EtwUnregister

EtwWriteEx

EtwWriteString

EtwWriteTransfer

EventDataDescCreate