Funzione UpdateTraceA (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 UpdateTraceA(
  CONTROLTRACE_ID         TraceId,
  LPCSTR                  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.

Requisiti

Vedi anche

ControlTrace