EventWriteString, fonction (evntprov.h)

Écrit un événement ETW qui contient une chaîne comme données. Cette fonction ne doit pas être utilisée.

Syntaxe

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

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] Level

Nombre 8 bits utilisé pour décrire la gravité ou l’importance d’un événement.

Pour plus d’informations sur le niveau d’événement , consultez EVENT_DESCRIPTOR .

[in] Keyword

Masque de bits 64 bits utilisé pour indiquer l’appartenance d’un événement à un ensemble de catégories d’événements.

Consultez EVENT_DESCRIPTOR pour plus d’informations sur la mot clé de l’événement.

[in] String

Chaîne terminée par nul à écrire en tant que données d’événement.

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

Cette API n’est pas utile et ne doit pas être utilisée.

• La plupart des outils d’analyse ETW ne prennent pas correctement en charge les événements de chaîne uniquement sans manifeste.
• Sans manifeste, les informations importantes sur l’événement (par exemple, le nom du fournisseur, l’ID d’événement et le nom de l’événement) ne sont pas disponibles, de sorte que les événements résultants sont difficiles à utiliser même lorsque l’outil d’analyse prend en charge les événements de chaîne uniquement.
• Avec un manifeste, cette fonction se comporte presque exactement comme le code d’un événement basé sur un manifeste avec un champ de chaîne unique. Toutefois, l’événement basé sur un manifeste est mieux pris en charge par les outils d’analyse des traces. En outre, le code généré par MC.exe pour un événement avec un champ de chaîne unique est plus efficace que la fonction EventWriteString .

Au lieu d’utiliser cette API, envisagez les alternatives suivantes :

• Utilisez TraceLoggingProvider.h pour écrire des événements qui sont bien pris en charge par les outils d’analyse ETW, fonctionnent sans manifeste et incluent des métadonnées telles que le nom du fournisseur et le nom de l’événement.
• Écrire un manifeste d’instrumentation. Créez un événement simple avec une seule valeur de chaîne terminée par nul. Vous pouvez écrire et collecter des événements même sans manifeste. Vous aurez uniquement besoin du manifeste pour décoder la trace collectée.

EventWriteString écrit un événement avec une charge utile de données composée de la chaîne spécifiée. Cette API est presque équivalente au code suivant :

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

L’événement résultant est le même que tout autre événement généré par EventWrite , sauf que l’indicateur EVENT_HEADER_FLAG_STRING_ONLY est défini pour l’événement résultant (voir EVENT_HEADER pour plus d’informations sur les indicateurs d’événement).

Notez que l’événement est écrit avec ID, Version, Opcode, Task et Channel définis sur 0.

Notez que l’événement utilise l’ID d’activité du thread actuel.

Les outils d’analyse ETW qui connaissent l’indicateur EVENT_HEADER_FLAG_STRING_ONLY peuvent extraire la valeur de chaîne même lorsque le décodeur ne peut pas localiser d’autres informations de décodage pour le fournisseur d’événements. Toutefois, sans manifeste, les outils ne pourront pas déterminer le nom du fournisseur de l’événement.

Spécifications

Voir aussi

EventWrite

TraceLoggingProvider.h