Partager via


OpenTraceW, fonction (evntrace.h)

La fonction OpenTrace ouvre un handle de traitement de trace ETW pour l’utilisation d’événements d’une session de suivi en temps réel ETW ou d’un fichier journal ETW.

Syntaxe

ETW_APP_DECLSPEC_DEPRECATED PROCESSTRACE_HANDLE WMIAPI OpenTraceW(
  [in, out] PEVENT_TRACE_LOGFILEW Logfile
);

Paramètres

[in, out] Logfile

Pointeur vers une structure EVENT_TRACE_LOGFILE . La structure spécifie la source à partir de laquelle consommer les événements (à partir d’un fichier journal ETW ou d’une session ETW en temps réel) et spécifie les rappels que le consommateur souhaite utiliser pour recevoir les événements. En cas de réussite, OpenTrace met à jour la structure avec les informations du fichier ou de la session ouverte.

Valeur retournée

Si la fonction réussit, elle retourne le handle de traitement de trace. Le handle doit être fermé à l’aide de CloseTrace.

Si la fonction échoue, elle retourne INVALID_PROCESSTRACE_HANDLE. (INVALID_PROCESSTRACE_HANDLE équivaut à (UINT64)UINTPTR_MAX.)

Notes

Avant Windows Vista, OpenTrace était retourné UINT64_MAX en cas de défaillance. Si votre code prend en charge les systèmes d’exploitation plus anciens (Windows XP ou Windows Server 2003) et les versions plus récentes de Windows (Windows Vista et versions ultérieures), vous devez déterminer le système d’exploitation sur lequel vous exécutez et comparer la valeur de retour à la valeur appropriée.

Système d’exploitation Type de processus Valeur indiquant un échec
Avant Windows Vista 32 ou 64 bits 0XFFFFFFFFFFFFFFFF = UINT64_MAX
Windows Vista ou version ultérieure ; 32 bits 0x00000000FFFFFFFF = (UINT64)UINTPTR_MAX
Windows Vista ou version ultérieure ; 64 bits 0XFFFFFFFFFFFFFFFF = (UINT64)UINTPTR_MAX

Si la fonction échoue, vous pouvez utiliser la fonction GetLastError pour obtenir des informations d’erreur étendues. Voici quelques erreurs courantes et leurs causes.

  • ERROR_INVALID_PARAMETER

    Le paramètre Logfile est NULL.

  • ERROR_BAD_PATHNAME

    Si vous n’avez pas spécifié le membre LoggerName de EVENT_TRACE_LOGFILE, vous devez spécifier un nom de fichier journal valide.

  • ERROR_ACCESS_DENIED

    Seuls les utilisateurs disposant de privilèges d’administration, les utilisateurs du groupe Utilisateurs du journal de performances et les services exécutés 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 de performances.

    Windows XP et Windows 2000 : Tout le monde peut consommer des événements en temps réel.

Remarques

Les consommateurs de trace appellent cette fonction pour ouvrir une session de traitement des traces.

Après avoir appelé OpenTrace, appelez la fonction ProcessTrace pour traiter les événements. Une fois que vous avez terminé le traitement des événements, appelez la fonction CloseTrace pour fermer le handle de traitement de trace.

Exemples

Pour obtenir un exemple qui utilise OpenTrace, consultez Utilisation de TdhFormatProperty pour consommer des données d’événement.

Notes

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

Voir aussi

EVENT_TRACE_LOGFILE

CloseTrace

ProcessTrace