Funzione UpdateTraceW (evntrace.h)
La funzione UpdateTrace aggiorna l'impostazione della proprietà della sessione di traccia eventi specificata.
questa funzione è obsoleta. La funzione ControlTrace sostituisce questa funzione.
Sintassi
ULONG WMIAPI UpdateTraceW(
CONTROLTRACE_ID TraceId,
LPCWSTR InstanceName,
PEVENT_TRACE_PROPERTIES Properties
);
Parametri
TraceId
InstanceName
Nome della sessione di traccia eventi da aggiornare o NULL. È necessario specificare InstanceName se TraceHandle è 0.
Per specificare la sessione Nt Kernel Logger, impostare InstanceNamesu KERNEL_LOGGER_NAME.
Properties
Puntatore a una struttura EVENT_TRACE_PROPERTIES inizializzata.
All'input, i membri devono specificare i nuovi valori per le proprietà da aggiornare. Per informazioni sulle proprietà che è possibile aggiornare, vedere Osservazioni.
Nell'output, i membri della struttura contengono le impostazioni e le statistiche aggiornate per la sessione di traccia eventi.
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_BAD_LENGTH
Il membro BufferSize del membro Wnode di Properties specifica una dimensione non corretta.
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 Properties non è valido.
- Il membro LoggerNameOffset di Properties non è valido.
Windows Server 2003 e Windows XP: Il membro Guid della struttura Wnode è SystemTraceControlGuid, ma il parametro InstanceName non è KERNEL_LOGGER_NAME.
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_UPDATE.
All'input, i membri devono specificare i nuovi valori per le proprietà da aggiornare. È possibile aggiornare le proprietà seguenti.
EnableFlags: impostare questo membro su 0 per disabilitare tutti i provider del kernel. In caso contrario, è necessario specificare i provider del kernel che si desidera abilitare o mantenere abilitati. Si applica solo alle sessioni di logger di sistema.
FlushTimer: impostare questo membro se si desidera 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. Se il 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 desidera attivare e disattivare EVENT_TRACE_REAL_TIME_MODE . Per disattivare l'utilizzo in tempo reale, impostare questo membro su 0. Per attivare il tempo reale, impostare questo membro su EVENT_TRACE_REAL_TIME_MODE e sarà OR con le modalità correnti.
MaximumBuffers: impostare questo membro se si desidera 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 LogFileNameOffset e FlushTimer.
Se si usa una struttura di EVENT_TRACE_PROPERTIES appena inizializzata, gli unici membri da specificare, ad eccezione dei membri che si stanno aggiornando, sono Wnode.BufferSize, Wnode.Guid e Wnode.Flags.
Se si utilizza la struttura di proprietà passata a StartTrace, assicurarsi che il membro LogFileNameOffset sia 0, a meno che non si stia modificando il nome del file di log.
Se si chiama la funzione ControlTrace per eseguire una query sulle proprietà della sessione corrente e quindi aggiornare tali proprietà per aggiornare la sessione, assicurarsi di impostare LogFileNameOffset su 0 (a meno che non si stia modificando il nome del file di log) e impostare EVENT_TRACE_PROPERTIES. Wnode.Flags per WNODE_FLAG_TRACED_GUID.
Per ottenere le impostazioni delle proprietà e le statistiche di sessione per una sessione di traccia eventi, chiamare la funzione ControlTrace .
Esempio
Per un esempio che usa UpdateTrace, vedere Aggiornamento di una sessione di traccia eventi.
Nota
L'intestazione evntrace.h definisce UpdateTrace 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 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | evntrace.h |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |