Fonction FlushTraceA (evntrace.h)
La fonction FlushTrace permet à une session de suivi d’événements de remettre immédiatement des événements mis en mémoire tampon pour la session spécifiée. Par défaut, une session de suivi d’événements remet des événements quand la mémoire tampon est pleine, que le FlushTimer de la session expire ou que la session est fermée.
Cette fonction est obsolète. La fonction ControlTrace remplace cette fonction.
Syntaxe
ULONG WMIAPI FlushTraceA(
CONTROLTRACE_ID TraceId,
[in] LPCSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties
);
Paramètres
TraceId
[in] InstanceName
Nom de la session de suivi des événements à vider ou NULL. Vous devez spécifier InstanceName si TraceHandle a la valeur 0.
Pour spécifier la session NT Kernel Logger, définissez InstanceNamesur KERNEL_LOGGER_NAME.
[in, out] Properties
Pointeur vers une structure EVENT_TRACE_PROPERTIES initialisée.
Si vous utilisez une structure nouvellement initialisée, il vous suffit de définir les membres Wnode.BufferSize, Wnode.Guid, LoggerNameOffset et LogFileNameOffset de la structure. Vous pouvez utiliser les longueurs maximales du nom de session (1 024 caractères) et du nom maximal du fichier journal (1 024 caractères) pour calculer la taille de la mémoire tampon et les décalages s’ils ne sont pas connus.
Lors de la sortie, la structure reçoit les paramètres de propriété et les statistiques de session de la session de suivi des événements, qui reflètent l’état de la session après le vidage.
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. Le tableau suivant inclut certaines erreurs courantes et leurs causes.
ERROR_INVALID_PARAMETER
Une des conditions suivantes est vraie :
- Les propriétés ont la valeur NULL.
- InstanceName et TraceHandle sont tous deux NULL.
- InstanceName a la valeur NULL et TraceHandle n’est pas un handle valide.
ERROR_BAD_LENGTH
Une des conditions suivantes est vraie :
- Le membre Wnode.BufferSize de Properties spécifie une taille incorrecte.
- Les propriétés n’ont pas suffisamment d’espace alloué pour contenir une copie du nom de session et du nom du fichier journal (le cas échéant).
ERROR_ACCESS_DENIED
Seuls les utilisateurs disposant de privilèges d’administration, les utilisateurs du groupe Utilisateurs du journal des performances et les services exécutés en tant que LocalSystem, LocalService, NetworkService peuvent contrôler les sessions de suivi des événements. Pour accorder à un utilisateur restreint la possibilité de contrôler les sessions de suivi, ajoutez-les au groupe Utilisateurs du journal des performances.
Windows XP et Windows 2000 : Tout le monde peut contrôler une session de suivi.
Remarques
Les contrôleurs de suivi d’événements appellent cette fonction.
Cette fonction est obsolète. Utilisez plutôt ControlTrace avec ControlCode défini sur EVENT_TRACE_CONTROL_FLUSH.
Cette fonction peut être utilisée avec une session en mémoire (session démarrée avec l’indicateur EVENT_TRACE_BUFFERING_MODE ) pour écrire les données de la trace dans un fichier.
Normalement, vous n’avez pas besoin de vider les sessions basées sur des fichiers ou en temps réel, car ETW vide automatiquement une mémoire tampon lorsqu’elle est pleine (c’est-à-dire lorsqu’elle n’a pas de place pour l’événement suivant), lorsque le FlushTimer de la session de suivi expire ou lorsque la session de trace est fermée.
N’appelez pas FlushTrace à partir de DllMain (peut provoquer un blocage).
Notes
L’en-tête evntrace.h définit FlushTrace 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
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | evntrace.h |
| Bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |