Funzione ControlTraceA (evntrace.h)
La funzione ControlTrace scarica, query, aggiornamenti o arresta la sessione di traccia eventi specificata.
Sintassi
ULONG WMIAPI ControlTraceA(
[in] TRACEHANDLE TraceHandle,
[in] LPCSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties,
[in] ULONG ControlCode
);
Parametri
[in] TraceHandle
Gestire una sessione di traccia eventi o 0. È necessario specificare un valore SessionHandle diverso da zero se SessionName è NULL. ETW ignora l'handle se SessionName non è NULL.
La funzione StartTrace restituisce questo handle quando viene avviata una nuova traccia. Per ottenere l'handle di una traccia esistente, usare ControlTrace per eseguire query sulle proprietà di traccia in base al nome della traccia e quindi ottenere l'handle dal campo Wnode.HistoricalContext dei dati restituiti EVENT_TRACE_PROPERTIES .
[in] InstanceName
Nome di una sessione di traccia eventi o NULL. È necessario specificare InstanceName se TraceHandle è 0.
Per specificare la sessione NT Kernel Logger, impostare InstanceName su KERNEL_LOGGER_NAME.
[in, out] Properties
Puntatore a una struttura di EVENT_TRACE_PROPERTIES inizializzata. Questa struttura deve essere zeroed-out prima di impostare tutti i campi.
Se ControlCode specifica EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERYoEVENT_TRACE_CONTROL_FLUSH, è necessario impostare solo i membri Wnode.BufferSize, Wnode.Guid, LoggerNameOffset e LogFileNameOffset della struttura EVENT_TRACE_PROPERTIES. Se la sessione è una sessione privata, è anche necessario impostare LogFileMode. È possibile usare il nome massimo della sessione (1024 caratteri) e il nome massimo del file di log (1024 caratteri) per calcolare le dimensioni del buffer e gli offset se non noti.
Se ControlCode specifica EVENT_TRACE_CONTROL_UPDATE, in input, i membri devono specificare i nuovi valori per le proprietà da aggiornare. In output, proprietà contiene le proprietà e le statistiche per la sessione di traccia eventi. È possibile aggiornare le proprietà seguenti.
EnableFlags: impostare questo membro su 0 per disabilitare tutti i provider di sistema. Impostare questo valore su un valore diverso da zero per specificare i provider di sistema che si desidera abilitare o mantenere abilitati. Questo può essere diverso da zero solo per i logger di sistema.
FlushTimer: impostare questo membro se si vuole modificare il tempo di attesa prima di scaricare i buffer. Se questo membro è 0, il membro non viene aggiornato.
LogFileNameOffset: impostare questo membro se si vuole passare a un altro file di log o per scaricare una traccia in modalità buffering su un nuovo file di log. Se questo membro è 0, il nome del file non viene aggiornato. Se l'offset non è zero e non si modifica il nome del file di log, la funzione restituisce un errore.
LogFileMode: impostare questo membro se si vuole attivare e disattivare EVENT_TRACE_REAL_TIME_MODE . Per disattivare il tempo reale, impostare questo membro su 0. Per attivare il tempo reale (creando una sessione che registra su disco e recapitando eventi in tempo reale), impostare questo membro su EVENT_TRACE_REAL_TIME_MODE e sarà OR con le modalità correnti.
MaximumBuffers: impostare questo membro se si vuole modificare il numero massimo di buffer usati da ETW. Se questo membro è 0, il membro non viene aggiornato.
Per le sessioni del logger privato, è possibile aggiornare solo i membri LogFileNameOffset e FlushTimer .
Se si usa una struttura di EVENT_TRACE_PROPERTIES appena inizializzata, zero-out la struttura, impostare Wnode.BufferSize, Wnode.Guid e Wnode.Flags e i valori da aggiornare.
Se si riutilizza una struttura EVENT_TRACE_PROPERTIES (ad esempio usando una struttura passata in precedenza a StartTrace o ControlTrace), assicurarsi di impostare il membro LogFileNameOffset su 0 a meno che non si modifica il nome del file di log e assicurarsi di impostare EVENT_TRACE_PROPERTIES. Wnode.Flags per WNODE_FLAG_TRACED_GUID.
A partire da Windows 10 versione 1703: per prestazioni migliori negli scenari tra processi, è ora possibile passare informazioni di filtro a ControlTrace per i loggger privati a livello di sistema. È necessario usare la struttura EVENT_TRACE_PROPERTIES_V2 per includere informazioni di filtro. Per altre informazioni, vedere Configurazione e avvio di una sessione del logger privato .
[in] ControlCode
Funzione di controllo richiesta. È possibile specificare uno dei valori seguenti:
EVENT_TRACE_CONTROL_FLUSH: scarica i buffer attivi della sessione.
Questa operazione può essere usata con una sessione in memoria (una sessione avviata con il flag di EVENT_TRACE_BUFFERING_MODE ) per scrivere i dati dalla traccia a 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 la sessione di traccia scade o quando la sessione di traccia viene chiusa.
Windows 2000: Questo valore non è supportato.
EVENT_TRACE_CONTROL_QUERY: recupera le proprietà e le statistiche della sessione.
EVENT_TRACE_CONTROL_STOP: arresta la sessione. L'handle di sessione non è più valido.
EVENT_TRACE_CONTROL_UPDATE: Aggiornamenti le proprietà della sessione.
EVENT_TRACE_CONTROL_INCREMENT_FILE: se la sessione ha ,
EVENT_TRACE_FILE_MODE_NEWFILEaggiorna la sessione per passare immediatamente al file successivo anziché attendere il riempimento del file precedente. Supportato a partire da Aggiornamento di Windows 10 (ottobre 2018).EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME: modifica una sessione in modalità file in una sessione in tempo reale (consente il recapito in tempo reale e disabilita la scrittura di eventi nel file ETL). Supportato a partire da Windows 10 aggiornamento di ottobre 2020.
Nota
Non è sicuro scaricare i buffer o arrestare una sessione di traccia da DllMain (potrebbe causare deadlock).
Valore restituito
Se la funzione ha esito positivo, il valore restituito è 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
Una delle seguenti condizioni è vera:
- Il membro Wnode.BufferSize di Proprietà 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_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.
- Il membro LogFileNameOffset di Proprietà non è valido.
- Il membro LoggerNameOffset di Proprietà non è valido.
- Il membro LogFileMode di Proprietà specifica una combinazione di flag non validi.
- Il membro Wnode.Guid di Properties è SystemTraceControlGuid, ma il parametro InstanceName non
KERNEL_LOGGER_NAMEè .
ERROR_BAD_PATHNAME
Un'altra sessione usa già il nome del file specificato dal membro LogFileNameOffset della struttura Proprietà .
ERROR_MORE_DATA
Il buffer per EVENT_TRACE_PROPERTIES è troppo piccolo per contenere tutte le informazioni per la sessione. Se non sono necessarie le informazioni sulla proprietà della sessione, è possibile ignorare questo errore. Se si riceve questo errore durante l'arresto della sessione, ETW avrà già arrestato la sessione prima di generare questo errore.
ERROR_ACCESS_DENIED
Solo gli utenti che eseguono con privilegi amministrativi elevati, gli utenti nel gruppo Utenti log prestazioni e i servizi in esecuzione come LocalSystem, LocalService, NetworkService possono controllare le sessioni di traccia degli eventi. Per concedere a un utente limitato la possibilità di controllare le sessioni di traccia, aggiungerle al gruppo Utenti log prestazioni. Solo gli utenti con privilegi e servizi amministrativi in esecuzione come LocalSystem possono controllare una sessione NT Kernel Logger.
Windows XP e Windows 2000: Chiunque può controllare una sessione di traccia.
ERROR_WMI_INSTANCE_NOT_FOUND
La sessione specificata non è in esecuzione.
Commenti
I controller di traccia eventi chiamano questa funzione.
Questa funzione sostituisce le funzioni FlushTrace, QueryTrace, StopTrace e UpdateTrace .
Nota
L'intestazione evntrace.h definisce ControlTrace come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
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; Advapi32.dll in Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per