EventWriteTransfer, fonction (evntprov.h)
Écrit un événement ETW avec un ID d’activité et un ID d’activité associé facultatif.
Syntaxe
ULONG EVNTAPI EventWriteTransfer(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[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, optional] ActivityId
Pointeur facultatif vers un ID d’activité 128 bits pour cet événement. Si ce n’est pas NULL, EventWriteTransfer utilise la valeur spécifiée pour l’ID d’activité de l’événement. S’il s’agit de NULL, EventWriteTransfer utilise l’ID d’activité du thread actuel.
Les outils de traitement des traces peuvent utiliser l’ID d’activité de l’événement pour organiser les événements en groupes appelés activités. Pour plus d’informations sur l’ID d’activité, consultez EventActivityIdControl.
[in, optional] RelatedActivityId
Pointeur facultatif vers un ID d’activité 128 bits qui est le parent de l’activité de cet événement. Si ce n’est pas NULL, EventWriteTransfer utilise la valeur spécifiée pour l’ID d’activité associé à l’événement. Si cette valeur est NULL, l’événement n’aura pas d’ID d’activité associé. L’ID d’activité associé est généralement défini sur l’événement START de l’activité (le premier événement de l’activité, enregistré avec Opcode = START).
Les outils de traitement des traces peuvent utiliser l’ID d’activité associé de l’événement pour déterminer la relation entre les activités, par exemple, l’activité associée est le parent de l’activité nouvellement démarrée. Pour plus d’informations sur l’ID d’activité associé, consultez EventActivityIdControl.
[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.
Remarques
La plupart des fournisseurs d’événements n’appellent pas EventWriteTransfer 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, EventWriteTransfer 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.
EventWriteTransfer achemine l’événement vers les sessions de suivi appropriées en fonction de l’Id de fournisseur (déterminé à partir de la 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 EventWriteTransfer.
EventWriteTransfer équivaut à EventWriteEx avec 0 pour filter et 0 pour les indicateurs.
Configuration requise
| Condition requise | Valeur |
|---|---|
| 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 |