Funzione FlushTraceA (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 FlushTraceA(
            CONTROLTRACE_ID         TraceId,
  [in]      LPCSTR                  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).

Requisiti

Vedi anche

ControlTrace