Fonction OpenTraceA (evntrace.h)
La fonction OpenTrace ouvre un handle de traitement des traces ETW pour la consommation d’événements à partir d’une session de suivi en temps réel ETW ou d’un fichier journal ETW.
Syntaxe
PROCESSTRACE_HANDLE WMIAPI OpenTraceA(
[in, out] PEVENT_TRACE_LOGFILEA 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 ouvert.
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 à la fois les anciens systèmes d’exploitation (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 l’é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 a la valeur 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 des 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 des 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 des traces.
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 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 |