structure EVENT_TRACE_LOGFILEA (evntrace.h)
La structure EVENT_TRACE_LOGFILE stocke des informations sur une source de données de trace.
La structure EVENT_TRACE_LOGFILE est utilisée lors de l’appel d’OpenTrace. L’utilisateur fournit une structure EVENT_TRACE_LOGFILE avec des informations sur la source de données de trace (soit le nom d’un fichier ETL, soit le nom d’une session d’enregistreur d’événements en temps réel active), les indicateurs de traitement des traces et les fonctions de rappel qui recevront des données de trace. En cas de réussite, OpenTrace remplit les champs restants de la structure pour retourner des détails sur la source de données de trace.
Lorsque ProcessTrace traite une mémoire tampon, il appelle le BufferCallback défini par l’utilisateur avec une structure EVENT_TRACE_LOGFILE pour fournir des informations sur la session de traitement des événements et la mémoire tampon.
Syntaxe
typedef struct _EVENT_TRACE_LOGFILEA {
LPSTR LogFileName;
LPSTR LoggerName;
LONGLONG CurrentTime;
ULONG BuffersRead;
union {
ULONG LogFileMode;
ULONG ProcessTraceMode;
} DUMMYUNIONNAME;
EVENT_TRACE CurrentEvent;
TRACE_LOGFILE_HEADER LogfileHeader;
PEVENT_TRACE_BUFFER_CALLBACKA BufferCallback;
ULONG BufferSize;
ULONG Filled;
ULONG EventsLost;
union {
PEVENT_CALLBACK EventCallback;
PEVENT_RECORD_CALLBACK EventRecordCallback;
} DUMMYUNIONNAME2;
ULONG IsKernelTrace;
PVOID Context;
} EVENT_TRACE_LOGFILEA, *PEVENT_TRACE_LOGFILEA;
Membres
LogFileName
Nom du fichier journal en cours de traitement ou NULL si les données d’une session de suivi en temps réel sont traitées. Spécifiez une valeur pour ce membre si vous appelez OpenTrace pour consommer des données à partir d’un fichier journal.
Lors de l’appel d’OpenTrace, si LoggerName n’a pas la valeur NULL , LogFileName doit avoir la valeur NULL.
Lors de l’appel d’OpenTrace, l’utilisateur qui consomme les événements doit disposer des autorisations nécessaires pour lire le fichier.
Notes
Le nom de fichier fourni à OpenTrace via le champ LogFileName doit être le nom de fichier complet, y compris les suffixes. Certaines API de création de fichiers de trace peuvent ajouter en mode silencieux un suffixe au nom de fichier spécifié par l’utilisateur. Par exemple, si le contrôleur a enregistré des événements dans une session privée (le contrôleur définit le membre LogFileMode de EVENT_TRACE_PROPERTIES sur EVENT_TRACE_PRIVATE_LOGGER_MODE lors de l’appel de StartTrace), le fichier ETL généré inclut un suffixe d’ID de processus, par exemple mytrace.etl_123.
Cela peut également se produire si le fichier a été créé à l’aide du mode EVENT_TRACE_FILE_MODE_NEWFILE , auquel cas le fichier ETL généré inclut un numéro de séquence.
LoggerName
Nom de la session de suivi des événements en temps réel ou NULL si les données d’un fichier journal sont traitées. Spécifiez une valeur pour ce membre si vous appelez OpenTrace pour consommer des données d’une session en temps réel.
Lors de l’appel d’OpenTrace, si LogFileName n’a pas la valeur NULL , LoggerName doit avoir la valeur NULL.
Vous ne pouvez consommer des événements en temps réel que si le contrôleur de trace a défini le membre LogFileMode de EVENT_TRACE_PROPERTIES pour inclure l’indicateur EVENT_TRACE_REAL_TIME_MODE .
Seuls les utilisateurs disposant de privilèges d’administration, les utilisateurs du groupe Utilisateurs du journal des performances et les applications s’exécutant en tant que LocalSystem, LocalService, NetworkService peuvent consommer des événements en temps réel. Pour accorder à un utilisateur restreint la possibilité de consommer des événements en temps réel, ajoutez-les au groupe Utilisateurs du journal des performances ou appelez EventAccessControl.
Windows XP et Windows 2000 : Tout le monde peut consommer des événements en temps réel.
CurrentTime
Sur la sortie, l’heure actuelle, par intervalles de 100 nanosecondes depuis minuit, le 1er janvier 1601.
BuffersRead
En sortie, le nombre de mémoires tampons traitées.
DUMMYUNIONNAME
DUMMYUNIONNAME.LogFileMode
Réservé. Ne pas utiliser.
DUMMYUNIONNAME.ProcessTraceMode
Modes pour le traitement des événements. Les modes sont définis dans le fichier d’en-tête evntcons.h . Vous pouvez spécifier un ou plusieurs des modes suivants :
PROCESS_TRACE_MODE_EVENT_RECORD
Spécifiez ce mode si vous souhaitez recevoir des événements dans le nouveau format EVENT_RECORD (fortement recommandé). Pour recevoir des événements dans le nouveau format, vous devez spécifier un rappel dans le membre EventRecordCallback . Si vous ne spécifiez pas ce mode, vous recevrez des événements dans l’ancien format via le rappel spécifié dans le membre EventCallback .
Avant Windows Vista : Non pris en charge.
PROCESS_TRACE_MODE_RAW_TIMESTAMP
Par défaut, ProcessTrace convertit le TimeStamp de l’événement au format brut d’origine (heure système, heure QPC ou compteur de cycle du processeur) en heure système (intervalles de 100 nanosecondes depuis minuit, le 1er janvier 1601).
Spécifiez l’indicateur PROCESS_TRACE_MODE_RAW_TIMESTAMP si vous ne souhaitez pas que la valeur d’horodatage dans le membre TimeStamp de EVENT_HEADER et EVENT_TRACE_HEADER convertie en heure système. Si cet indicateur est spécifié, ProcessTrace laisse la valeur d’horodatage au format d’origine spécifié par le contrôleur dans le membre Wnode.ClientContext de EVENT_TRACE_PROPERTIES.
Avant Windows Vista : Non pris en charge.
PROCESS_TRACE_MODE_REAL_TIME
Spécifiez ce mode pour recevoir des événements en temps réel. Vous devez spécifier ce mode si LoggerName n’a pas la valeur NULL.
CurrentEvent
Lors de la sortie, une structure EVENT_TRACE qui contient le dernier événement traité.
LogfileHeader
En sortie, une structure de TRACE_LOGFILE_HEADER qui contient des informations générales sur la session et l’ordinateur sur lequel la session s’est exécutée.
BufferCallback
Pointeur vers la fonction BufferCallback qui reçoit des statistiques liées à la mémoire tampon pour chaque vidage ETW de mémoire tampon. ETW appelle ce rappel après avoir émis tous les événements dans la mémoire tampon. Ce rappel est facultatif.
BufferSize
Sur la sortie, contient la taille de chaque mémoire tampon, en octets.
Filled
Sur la sortie, contient le nombre d’octets dans la mémoire tampon qui contiennent des informations valides.
EventsLost
Non utilisé.
DUMMYUNIONNAME2
DUMMYUNIONNAME2.EventCallback
Pointeur vers la fonction EventCallback que ETW appelle pour chaque événement de la mémoire tampon. Ce champ est utilisé uniquement si le champ ProcessTraceMode n’inclut pas l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD .
Notes
Le champ EventCallback sera traité comme un EventRecordCallback si le champ ProcessTraceMode inclut l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD . Si votre EventCallback reçoit des données garblées de ProcessTrace, vérifiez que le champ ProcessTraceMode n’inclut pas l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD .
Conseil
Le nouveau code doit utiliser EventRecordCallback au lieu d’EventCallback. EventRecordCallback reçoit un EVENT_RECORD qui contient des informations d’événement plus complètes, peut être utilisé avec des API de décodage telles que TdhGetEventInformation, et a un pointeur de contexte qui peut être utilisé par votre rappel.
DUMMYUNIONNAME2.EventRecordCallback
Pointeur vers la fonction EventRecordCallback que ETW appelle pour chaque événement de la mémoire tampon. Ce champ est utilisé uniquement si le champ ProcessTraceMode inclut l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD .
Notes
Le champ EventRecordCallback sera traité comme un EventCallback si le champ ProcessTraceMode n’inclut pas l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD . Si votre EventRecordCallback reçoit des données altérées de ProcessTrace, vérifiez que le champ ProcessTraceMode inclut l’indicateur PROCESS_TRACE_MODE_EVENT_RECORD .
Avant Windows Vista : Non pris en charge.
IsKernelTrace
Sur la sortie, si ce membre a la valeur TRUE, la session de suivi des événements est l’enregistreur d’événements NT Kernel Logger. Sinon, il s’agit d’une autre session de suivi d’événements.
Context
Données de contexte qu’un consommateur peut spécifier lors de l’appel d’OpenTrace. Si le consommateur utilise EventRecordCallback pour consommer des événements, ETW définit le membre UserContext de la structure EVENT_RECORD sur cette valeur.
Avant Windows Vista : Non pris en charge.
Notes
Les consommateurs d’événements doivent :
- Initialisez la mémoire de cette structure à zéro.
- Si vous lisez à partir d’un fichier ETL, définissez LogFileName sur le chemin d’accès au fichier.
Sinon (par exemple, en cas de lecture à partir d’une session en temps réel), définissez LoggerName sur le nom de la session et définissez ProcessTraceMode sur
PROCESS_TRACE_MODE_REAL_TIME. - Si vous utilisez EventRecordCallback (recommandé), définissez EventRecordCallback sur l’adresse de votre fonction de rappel d’enregistrement d’événement, définissez Context sur une valeur à fournir à votre rappel et ajoutez
PROCESS_TRACE_MODE_EVENT_RECORDà ProcessTraceMode. Sinon (par exemple, si vous utilisez EventCallback), définissez EventCallback sur l’adresse de votre fonction de rappel d’événement. - Si vous avez besoin d’un rappel après le traitement de chaque mémoire tampon, définissez BufferCallback sur l’adresse de votre fonction de rappel de mémoire tampon.
- Si vous souhaitez obtenir les données d’horodatage brutes d’origine au lieu de l’horodatage traité, ajoutez
PROCESS_TRACE_MODE_RAW_TIMESTAMPà ProcessTraceMode. - Appelez OpenTrace. Notez que si elle réussit, la fonction OpenTrace remplit les membres de cette structure avec des informations provenant de la source de données de trace.
- Appelez ProcessTrace avec le handle retourné par OpenTrace.
- ProcessTrace appelle votre fonction de rappel d’événement pour chaque événement.
- ProcessTrace appellera votre fonction de rappel de mémoire tampon (si elle est fournie) après avoir terminé chaque mémoire tampon et inclura une instance de la structure de EVENT_TRACE_LOGFILE avec le traitement des traces status informations.
- Une fois le traitement de la trace terminé, appelez CloseTrace pour fermer le handle retourné par OpenTrace.
Notes
L’en-tête evntrace.h définit EVENT_TRACE_LOGFILE comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Configuration requise
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| En-tête | evntrace.h |