Funzione OpenTraceA (evntrace.h)
La funzione OpenTrace apre un handle di elaborazione di traccia ETW per l'utilizzo di eventi da una sessione di traccia ETW in tempo reale o da un file di log ETW.
Sintassi
PROCESSTRACE_HANDLE WMIAPI OpenTraceA(
[in, out] PEVENT_TRACE_LOGFILEA Logfile
);
Parametri
[in, out] Logfile
Puntatore a una struttura EVENT_TRACE_LOGFILE . La struttura specifica l'origine da cui utilizzare gli eventi (da un file di log ETW o una sessione ETW in tempo reale) e specifica i callback che il consumer desidera utilizzare per ricevere gli eventi. In caso di esito positivo, OpenTrace aggiornerà la struttura con le informazioni del file o della sessione aperta.
Valore restituito
Se la funzione ha esito positivo, restituisce l'handle di elaborazione della traccia. L'handle deve essere chiuso usando CloseTrace.
Se la funzione ha esito negativo, restituisce INVALID_PROCESSTRACE_HANDLE.
(INVALID_PROCESSTRACE_HANDLE equivale a (UINT64)UINTPTR_MAX.)
Nota
Prima di Windows Vista, OpenTrace restituito UINT64_MAX in caso di errore. Se il codice supporta entrambi i sistemi operativi precedenti (Windows XP o Windows Server 2003) e le versioni più recenti di Windows (Windows Vista e versioni successive), è necessario determinare il sistema operativo in cui si esegue e confrontare il valore restituito con il valore appropriato.
| Sistema operativo | Tipo di processo | Valore che indica l'errore |
|---|---|---|
| Prima di Windows Vista | 32 o 64 bit | 0XFFFFFFFFFFFFFFFF = UINT64_MAX |
| Windows Vista o versioni successive | 32 bit | 0x00000000FFFFFFFF = (UINT64)UINTPTR_MAX |
| Windows Vista o versioni successive | 64 bit | 0XFFFFFFFFFFFFFFFF = (UINT64)UINTPTR_MAX |
Se la funzione ha esito negativo, è possibile usare la funzione GetLastError per ottenere informazioni estese sull'errore. Di seguito sono riportati alcuni errori comuni e le relative cause.
ERROR_INVALID_PARAMETER
Il parametro Logfile è NULL.
ERROR_BAD_PATHNAME
Se non è stato specificato il membro LoggerName di EVENT_TRACE_LOGFILE, è necessario specificare un nome di file di log valido.
ERROR_ACCESS_DENIED
Solo gli utenti con privilegi amministrativi, gli utenti nel gruppo Performance Log Users e i servizi in esecuzione come LocalSystem, LocalService, NetworkService possono utilizzare gli eventi in tempo reale. Per concedere a un utente con restrizioni la possibilità di utilizzare gli eventi in tempo reale, aggiungerli al gruppo Utenti del log delle prestazioni.
Windows XP e Windows 2000: Chiunque può utilizzare eventi in tempo reale.
Commenti
I consumer di traccia chiamano questa funzione per aprire una sessione di elaborazione di traccia.
Dopo aver chiamato OpenTrace, chiamare la funzione ProcessTrace per elaborare gli eventi. Al termine dell'elaborazione degli eventi, chiamare la funzione CloseTrace per chiudere l'handle di elaborazione della traccia.
Esempio
Per un esempio che usa OpenTrace, vedere Using TdhFormatProperty to Consume Event Data.For an example that using OpenTrace, see Using TdhFormatProperty to Consume Event Data.
Nota
L'intestazione evntrace.h definisce OpenTrace come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [app desktop | App UWP] |
| Server minimo supportato | Windows 2000 Server [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | evntrace.h |
| Libreria | Sechost.lib in Windows 8.1 e Windows Server 2012 R2; Advapi32.lib in Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |
| DLL | Sechost.dll in Windows 8.1 e Windows Server 2012 R2; Advapi32.dll in Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |