Funzione ControlTraceA (evntrace.h)
La funzione ControlTrace scarica, query, aggiornamenti o arresta la sessione di traccia eventi specificata.
Sintassi
ULONG WMIAPI ControlTraceA(
CONTROLTRACE_ID TraceId,
[in] LPCSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties,
[in] ULONG ControlCode
);
Parametri
TraceId
[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 migliorare le prestazioni 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: aggiorna 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 Windows 10 Ottobre 2018 Update.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 Ottobre 2020 Update.
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 |