Share via

Fonction StopTraceA (evntrace.h)

  • Article

La fonction StopTrace arrête la session de suivi des événements spécifiée.

Cette fonction est obsolète. La fonction ControlTrace remplace cette fonction.

Syntaxe

ULONG WMIAPI StopTraceA(
  TRACEHANDLE             TraceHandle,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Paramètres

TraceHandle

Gérez la session de suivi d’événements à arrêter, ou 0. Vous devez spécifier une TraceHandle autre que zéro si InstanceName a la valeur NULL. Ce paramètre sera utilisé uniquement si InstanceName a la valeur NULL. Le handle est retourné par StartTrace.

InstanceName

Nom de la session de suivi des é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, 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.

À compter de Windows 10, version 1703 : Pour de meilleures performances dans les scénarios inter-processus, vous pouvez maintenant passer le filtrage à StopTrace pour les enregistreurs d’journaux privés à l’échelle du système. Vous devez transmettre la nouvelle structure 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 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_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 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_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 provoquer un blocage).

Notes

L’en-tête evntrace.h définit StopTrace 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 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

Voir aussi

ControlTrace

StartTrace