Fonction TraceEvent (evntrace.h)

  • Article

Un fournisseur d’événements basé sur RegisterTraceGuids (« Classique ») utilise la fonction TraceEvent pour envoyer un événement structuré à une session de suivi d’événements.

Syntaxe

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

Paramètres

[in] TraceHandle

Gérez la session de suivi des événements qui enregistre l’événement. Le fournisseur obtient le handle lorsqu’il appelle la fonction GetTraceLoggerHandle dans son implémentation ControlCallback .

[in] EventTrace

Pointeur vers une structure EVENT_TRACE_HEADER . Les données spécifiques à l’événement sont éventuellement ajoutées à la structure. Le plus grand événement que vous pouvez enregistrer est légèrement inférieur à 64 000. Vous devez spécifier des valeurs pour les membres suivants de la structure EVENT_TRACE_HEADER .

  • Taille
  • Guid ou GuidPtr
  • Indicateurs

En fonction de la complexité des informations fournies par votre fournisseur, vous devez également envisager de spécifier des valeurs pour les membres suivants.

  • Class.Type
  • Class.Level

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur système. Voici quelques erreurs courantes et leurs causes.

  • ERROR_INVALID_FLAG_NUMBER

    Le membre Flags de la structure EVENT_TRACE_HEADER est incorrect.

  • ERROR_INVALID_HANDLE

    TraceHandle n’est pas valide ou spécifie le handle de session de l’enregistreur d’événements du noyau NT.

  • ERROR_NOT_ENOUGH_MEMORY

    La session est à court de mémoire tampon sur laquelle écrire. Cela peut se produire en cas de taux élevé d'événements parce que le sous-système du disque est surchargé ou le nombre de mémoires tampon est trop petit. Plutôt que de bloquer jusqu’à ce que d’autres mémoires tampons soient disponibles, TraceEvent ignore l’événement.

    Pensez à augmenter le nombre et la taille des mémoires tampon pour la session, à réduire le nombre d'événements écrits ou à réduire la taille des événements.

    Windows 2000 : Non pris en charge.

  • ERROR_OUTOFMEMORY

    L’événement est ignoré car, bien que le pool de mémoires tampons n’ait pas atteint sa taille maximale, la mémoire disponible est insuffisante pour allouer une mémoire tampon supplémentaire et aucune mémoire tampon n’est disponible pour recevoir l’événement.

  • ERROR_INVALID_PARAMETER

    Une des conditions suivantes est vraie :

    • TraceHandle a la valeur NULL.
    • EventTrace a lavaleur NULL.
    • Le membre Size de la structure EVENT_TRACE_HEADER est incorrect.

  • ERROR_MORE_DATA

    Les données d’un événement unique ne peuvent pas s’étendre sur plusieurs mémoires tampons. Un événement de trace est limité à la taille de la mémoire tampon de la session de suivi d’événements moins la taille de la structure EVENT_TRACE_HEADER .

Notes

Les fournisseurs ETW basés sur MOF appellent cette fonction.

Notes

La plupart des développeurs n’appellent pas cette fonction. Cette API prend en charge l’ETW basé sur MOF, mais l’ETW basé sur MOF est déconseillé au profit de l’ETW basé sur un manifeste. En outre, la plupart des fournisseurs basés sur MOF utilisent des fonctions wrapper générées par MC.exe au lieu d’appeler directement les API ETW.

Avant que le fournisseur puisse appeler cette fonction, le fournisseur

  • Vous devez appeler la fonction RegisterTraceGuids pour s’inscrire et la classe de trace d’événement.
  • Doit être activé. Un contrôleur appelle la fonction EnableTrace pour activer un fournisseur.

L’événement est écrit dans un fichier journal, envoyé aux consommateurs de suivi d’événements en temps réel, ou les deux. Le membre LogFileMode de la structure EVENT_TRACE_PROPERTIES passée à StartTrace définit l’emplacement d’envoi de l’événement.

Les événements de trace sont écrits dans l’ordre dans lequel ils se produisent.

Pour suivre un ensemble d’événements associés, utilisez la fonction TraceEventInstance .

Sur Windows Vista, vous devez utiliser la fonction EventWrite pour journaliser les événements.

Exemples

Pour obtenir un exemple qui utilise TraceEvent, consultez Événements de suivi.

Spécifications

   
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête evntrace.h
Bibliothèque Advapi32.lib
DLL Advapi32.dll

Voir aussi

EVENT_TRACE_HEADER

EnableTrace

RegisterTraceGuids

TraceEventInstance