Condividi tramite


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

Vedi anche

CloseTrace

EVENT_TRACE_LOGFILE

ProcessTrace