Funzione FlushTraceW (evntrace.h)
La funzione FlushTrace fa sì che una sessione di traccia eventi recapita immediatamente eventi memorizzati nel buffer per la sessione specificata. Per impostazione predefinita, una sessione di traccia eventi recapita gli eventi quando un buffer è pieno, flushtimer della sessione scade o la sessione viene chiusa.
questa funzione è obsoleta. La funzione ControlTrace sostituisce questa funzione.
Sintassi
ULONG WMIAPI FlushTraceW(
CONTROLTRACE_ID TraceId,
[in] LPCWSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties
);
Parametri
TraceId
[in] InstanceName
Nome della sessione di traccia eventi da scaricare o NULL. È necessario specificare InstanceName se TraceHandle è 0.
Per specificare la sessione Nt Kernel Logger, impostare InstanceNamesu KERNEL_LOGGER_NAME.
[in, out] Properties
Puntatore a una struttura EVENT_TRACE_PROPERTIES inizializzata.
Se si usa una struttura appena inizializzata, è sufficiente impostare i membri Wnode.BufferSize, Wnode.Guid, LoggerNameOffset e LogFileNameOffset della struttura. È possibile usare il nome massimo della sessione (1024 caratteri) e la lunghezza massima del nome file di log (1024 caratteri) per calcolare le dimensioni e gli offset del buffer, se non noti.
Nell'output, la struttura riceve le impostazioni delle proprietà e le statistiche di sessione della sessione di traccia eventi, che riflettono lo stato della sessione dopo lo scaricamento.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore di sistema. La tabella seguente include alcuni errori comuni e le relative cause.
ERROR_INVALID_PARAMETER
Una delle seguenti condizioni è vera:
- Le proprietà sono NULL.
- InstanceName e TraceHandle sono entrambi NULL.
- InstanceName è NULL e TraceHandle non è un handle valido.
ERROR_BAD_LENGTH
Una delle seguenti condizioni è vera:
- Il membro Wnode.BufferSize di Properties specifica una dimensione non corretta.
- Le proprietà non dispongono di spazio sufficiente allocato per contenere una copia del nome della sessione e del nome del file di log (se usato).
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 controllare le sessioni di traccia degli eventi. Per concedere a un utente con restrizioni la possibilità di controllare le sessioni di traccia, aggiungerle al gruppo Performance Log Users .
Windows XP e Windows 2000: Chiunque può controllare una sessione di traccia.
Commenti
I controller di traccia eventi chiamano questa funzione.
questa funzione è obsoleta. Usare invece ControlTrace con ControlCode impostato su EVENT_TRACE_CONTROL_FLUSH.
Questa funzione può essere usata con una sessione in memoria (una sessione avviata con il flag EVENT_TRACE_BUFFERING_MODE ) per scrivere i dati dalla traccia in un file.
In genere non è necessario scaricare sessioni basate su file o in tempo reale perché ETW scarica automaticamente un buffer quando è pieno (ad esempio quando non ha spazio per l'evento successivo), quando il flushTimer della sessione di traccia scade o quando la sessione di traccia viene chiusa.
Non chiamare FlushTrace da DllMain (può causare deadlock).
Nota
L'intestazione evntrace.h definisce FlushTrace 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 XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | evntrace.h |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |