StopTraceA, fonction (evntrace.h)
La fonction StopTrace arrête la session de suivi d’événements spécifiée.
Cette fonction est obsolète. La fonction ControlTrace remplace cette fonction.
Syntaxe
ULONG WMIAPI StopTraceA(
CONTROLTRACE_ID TraceId,
LPCSTR InstanceName,
PEVENT_TRACE_PROPERTIES Properties
);
Paramètres
TraceId
InstanceName
Nom de la session de suivi d’événements à arrêter, 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.
Properties
Pointeur vers une structure EVENT_TRACE_PROPERTIES qui reçoit les propriétés et statistiques finales de la session.
Si vous utilisez une structure nouvellement initialisée, vous devez uniquement définir les membres Wnode.BufferSize, Wnode.Guid, LoggerNameOffset et LogFileNameOffset de la structure. Vous pouvez utiliser les longueurs maximales de nom de session (1 024 caractères) et de nom de 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.
À compter de Windows 10, version 1703 : Pour de meilleures performances dans les scénarios inter-processus, vous pouvez désormais transmettre le filtrage à StopTrace pour les enregistreurs d’événements privés à l’échelle du système. Vous devez transmettre la nouvelle structure de EVENT_TRACE_PROPERTIES_V2 pour inclure les informations de filtrage. Pour plus d’informations, consultez Configuration et démarrage d’une session d’enregistreur d’événements privés .
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_BAD_LENGTH
Une des conditions suivantes est vraie :
- Le membre Wnode.BufferSize de Properties spécifie une taille incorrecte.
- Les propriétés ne disposent pas d’un espace suffisant pour contenir une copie du nom de session et du nom du fichier journal (le cas échéant).
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_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 d’événements. Pour accorder à un utilisateur restreint la possibilité de contrôler les sessions de suivi, ajoutez-les au groupe Utilisateurs du journal de performances.
Windows XP et Windows 2000 : Tout le monde peut contrôler une session de suivi.
Remarques
Les contrôleurs de trace d’événements appellent cette fonction.
Cette fonction est obsolète. Utilisez plutôt ControlTrace avec ControlCode défini sur EVENT_TRACE_CONTROL_STOP.
Si LogFileMode contient EVENT_TRACE_FILE_MODE_PREALLOCATE, StartTrace étend le fichier journal aux octets MaximumFileSize . Le fichier occupe tout l’espace pendant la journalisation, pour les journaux circulaires et séquentiels. Lorsque vous arrêtez l’enregistreur d’événements, le fichier journal est réduit à la taille nécessaire.
N’appelez pas StopTrace à partir de DllMain (peut entraîner un blocage).
Notes
L’en-tête evntrace.h définit StopTrace en tant qu’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. La combinaison 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 2000 Professionnel [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau | Applications UWP] |
| Plateforme cible | Windows |
| En-tête | evntrace.h |
| Bibliothèque | Sechost.lib sur Windows 8.1 et Windows Server 2012 R2 ; Advapi32.lib sur Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista et Windows XP |
| DLL | Sechost.dll sur Windows 8.1 et Windows Server 2012 R2 ; Advapi32.dll sur Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista et Windows XP |