Funzione ProcessTrace (evntrace.h)

Articolo
08/23/2023

La funzione ProcessTrace recapita gli eventi da una o più sessioni di elaborazione di traccia ETW al consumer.

Sintassi

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PTRACEHANDLE HandleArray,
  [in] ULONG        HandleCount,
  [in] LPFILETIME   StartTime,
  [in] LPFILETIME   EndTime
);

Parametri

[in] HandleArray

Puntatore a una matrice di handle di sessione di elaborazione di traccia ottenuti dalle chiamate precedenti alla funzione OpenTrace .

La matrice può contenere fino a 64 handle per le sessioni di elaborazione file oppure può contenere un handle per una sessione di elaborazione in tempo reale. La matrice non può contenere sia handle di sessione di elaborazione file che handle di sessione di elaborazione in tempo reale.

[in] HandleCount

Numero di elementi in HandleArray.

[in] StartTime

Puntatore a una struttura FILETIME facoltativa che specifica il periodo di tempo di inizio per cui si desidera ricevere gli eventi. La funzione non recapita gli eventi con timestamp prima di StartTime.

[in] EndTime

Puntatore a una struttura FILETIME facoltativa che specifica il periodo di tempo di fine per cui si desidera ricevere gli eventi. La funzione non recapita gli eventi con timestamp dopo EndTime.

Windows Server 2003: Questo valore viene ignorato per il recapito di eventi in tempo reale.

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. Di seguito sono riportati alcuni errori comuni e le relative cause.

ERROR_BAD_LENGTH

HandleCount non è valido o il numero di handle è maggiore di 64.
ERROR_INVALID_HANDLE

Un elemento di HandleArray non è un handle di sessione di traccia eventi valido.
ERROR_INVALID_TIME

EndTime è minore di StartTime.
ERROR_INVALID_PARAMETER

HandleArray è NULL, contiene sia sessioni di elaborazione file che sessioni di elaborazione in tempo reale oppure contiene più di una sessione di elaborazione in tempo reale.
ERROR_NOACCESS

Si è verificata un'eccezione in una delle funzioni di callback che riceve gli eventi.
ERROR_CANCELLED

Indica l'elaborazione annullata dal consumer restituendo FALSE nella relativa funzione BufferCallback .
ERROR_WMI_INSTANCE_NOT_FOUND

La sessione di raccolta di tracce da cui si sta tentando di utilizzare gli eventi in tempo reale non è in esecuzione o non ha la modalità di traccia in tempo reale abilitata.

Commenti

I consumer di traccia chiamano questa funzione per elaborare gli eventi da una o più sessioni di elaborazione di traccia. Questa funzione blocca fino al termine dell'elaborazione.

Prima di chiamare ProcessTrace, usare OpenTrace per aprire handle per tracciare le sessioni di elaborazione.

La funzione ProcessTrace recapita gli eventi dalle sessioni richiamando le funzioni di callback BufferCallback, EventCallback e EventRecordCallback del consumer.

La funzione ProcessTrace tenta di recapitare gli eventi in ordine in base al timestamp dell'evento( ad esempio tenta di recapitare gli eventi meno recenti al più recente). In alcuni casi , ProcessTrace potrebbe recapitare eventi non in ordine.

Se l'orologio utilizzato per i timestamp dell'evento viene regolato all'indietro durante la raccolta di tracce, l'ordine di recapito degli eventi è imprevedibile. Per evitare questo problema, usare l'orologio QPC anziché l'orologio dell'ora di sistema durante la raccolta della traccia.
Se più eventi vengono raccolti con lo stesso timestamp su CPU diverse, l'ordine di recapito degli eventi è imprevedibile.
Se un evento ha un timestamp non valido (ad esempio a causa del danneggiamento del file), l'ordine di recapito di tale evento e altri eventi nella traccia potrebbe essere imprevedibile.

La funzione ProcessTrace blocca il thread finché non recapita tutti gli eventi, la funzione BufferCallback restituisce FALSE oppure si chiama CloseTrace. Inoltre, se il consumer utilizza eventi in tempo reale, la funzione ProcessTrace viene restituita dopo che il controller arresta la sessione di traccia. Si noti che potrebbe verificarsi un ritardo di alcuni secondi prima che la funzione restituisca.

Windows Server 2003: È possibile chiamare CloseTrace solo dopo la restituzione di ProcessTrace .

Esempio

Per un esempio che usa ProcessTrace, vedere Using TdhFormatProperty to Consume Event Data.For an example that using ProcessTrace, see Using TdhFormatProperty to Consume Event Data.

Requisiti


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