EventWrite, fonction (evntprov.h)
Écrit un événement ETW qui utilise l’ID d’activité du thread actuel.
Syntaxe
ULONG EVNTAPI EventWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Paramètres
[in] RegHandle
Handle d’inscription du fournisseur. Le handle provient d’EventRegister. L’événement généré utilise le ProviderId associé au handle.
[in] EventDescriptor
EVENT_DESCRIPTOR avec des informations sur l’événement (métadonnées), notamment l’ID, la version, le niveau, le mot clé, le canal, le code d’opération et la tâche.
Important
ProviderId, Level et Keyword sont les principaux moyens de filtrage des événements. D’autres types de filtrage sont possibles, mais ont une surcharge beaucoup plus élevée. Affectez toujours un niveau différent de zéro et mot clé à chaque événement.
[in] UserDataCount
Nombre de structures EVENT_DATA_DESCRIPTOR dans UserData. Le nombre maximal est 128.
[in, optional] UserData
Tableau de structures UserDataCountEVENT_DATA_DESCRIPTOR qui décrivent les données à inclure dans l’événement. UserData peut avoir la valeur NULL si UserDataCount est égal à zéro.
Chaque EVENT_DATA_DESCRIPTOR décrit un bloc de mémoire à inclure dans l’événement. Les blocs spécifiés seront concaténés dans l’ordre sans remplissage ni alignement pour former le contenu de l’événement. Si vous utilisez le décodage basé sur un manifeste, le contenu de l’événement doit correspondre à la disposition spécifiée dans le modèle associé à l’événement dans le manifeste.
Valeur retournée
Retourne ERROR_SUCCESS en cas de réussite ou un code d’erreur. Les codes d’erreur possibles sont les suivants :
- ERROR_INVALID_PARAMETER : un ou plusieurs paramètres ne sont pas valides.
- ERROR_INVALID_HANDLE : le handle d’inscription du fournisseur n’est pas valide.
- ERROR_ARITHMETIC_OVERFLOW : la taille de l’événement est supérieure à la valeur maximale autorisée (64 Ko - en-tête).
- ERROR_MORE_DATA : la taille de la mémoire tampon de session est trop petite pour l’événement.
- ERROR_NOT_ENOUGH_MEMORY : se produit lorsque des mémoires tampons remplies tentent de vider sur le disque, mais que les E/S de disque ne se produisent pas assez rapidement. Cela se produit lorsque le disque est lent et que le trafic d’événements est lourd. Finalement, il n’y a plus de mémoires tampons libres (vides) et l’événement est supprimé.
- STATUS_LOG_FILE_FULL : le fichier de lecture en temps réel est plein. Les événements ne sont pas consignés dans la session tant qu’un consommateur en temps réel n’utilise pas les événements du fichier de lecture.
Le code d’erreur est principalement destiné à être utilisé dans les scénarios de débogage et de diagnostic. La plupart du code de production doit continuer à s’exécuter et continuer à signaler des événements même si un événement ETW n’a pas pu être écrit. Les builds de mise en production doivent donc généralement ignorer le code d’erreur.
Notes
La plupart des fournisseurs d’événements n’appellent pas EventWrite directement. Au lieu de cela, la plupart des fournisseurs d’événements sont implémentés à l’aide d’une infrastructure ETW qui encapsule les appels à EventRegister, EventWrite et EventUnregister. Par exemple, vous pouvez écrire un manifeste d’événement , puis utiliser le compilateur de messages pour générer du code C/C++ pour les événements, ou vous pouvez utiliser TraceLogging pour éviter d’avoir besoin d’un manifeste.
EventWrite achemine l’événement vers les sessions de suivi appropriées en fonction du ProviderId (déterminé à partir du RegHandle), du niveau, du mot clé et d’autres caractéristiques de l’événement. Si aucune session de trace n’enregistre cet événement, cette fonction ne fait rien et retourne ERROR_SUCCESS.
Pour réduire l’impact sur les performances des événements qui ne sont enregistrés par aucune session de trace, vous pouvez appeler EventEnabled pour déterminer si une session de trace enregistre votre événement avant de préparer les données et d’appeler EventWrite.
EventWrite définit l’ID d’activité de l’événement sur l’ID d’activité du thread actuel. EventWrite n’inclut pas d’ID d’activité associé dans l’événement. Pour spécifier un ID d’activité différent ou pour ajouter un ID d’activité associé, utilisez EventWriteTransfer.
EventWrite équivaut à EventWriteEx avec 0 pour Filter, 0 pour Flags, NULL pour ActivityId et NULL pour RelatedActivityId.
Spécifications
| Client minimal pris en charge | Windows Vista [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | evntprov.h |
| Bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |