Funzione EnableTraceEx (evntrace.h)

Un controller di sessione di traccia chiama EnableTraceEx per configurare il modo in cui un provider di eventi ETW registra gli eventi in una sessione di traccia.

questa funzione è obsoleta. La funzione EnableTraceEx2 sostituisce questa funzione.

Sintassi

ULONG WMIAPI EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
                 CONTROLTRACE_ID          TraceId,
  [in]           ULONG                    IsEnabled,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    EnableProperty,
  [in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);

Parametri

[in] ProviderId

ID provider (GUID di controllo) del provider di eventi da configurare.

[in, optional] SourceId

GUID che può identificare in modo univoco l'origine di questa richiesta di configurazione o NULL se non è necessaria alcuna identità di origine (equivalente all'impostazione di SourceId su &GUID_NULL). Se specificato, questo valore viene usato come parametro SourceId quando si richiama l'oggetto EnableCallback del provider.

TraceId

[in] IsEnabled

Impostare su 1 per abilitare la ricezione di eventi dal provider o per modificare le impostazioni usate durante la ricezione di eventi dal provider, ad esempio per modificare il livello e le parole chiave. Impostare su 0 per disabilitare la ricezione di eventi dal provider.

[in] Level

Valore che indica il livello massimo di eventi che il provider deve scrivere. Il provider scrive in genere un evento se il livello dell'evento è minore o uguale a questo valore, oltre a soddisfare i criteri MatchAnyKeyword e MatchAllKeyword .

Microsoft definisce la semantica dei livelli 1-5, come illustrato di seguito. I valori inferiori indicano eventi più gravi. Ogni valore di EnableLevel abilita il livello specificato e tutti i livelli più gravi. Ad esempio, se si specifica TRACE_LEVEL_WARNING, il consumer riceverà avvisi, errori ed eventi critici.

Le TRACE_LEVEL costanti sono definite in evntrace.h. Le costanti equivalenti WINMETA_LEVEL sono definite in winmeta.h.

[in] MatchAnyKeyword

Maschera di parole chiave a 64 bit che determinano le categorie di eventi che si desidera che il provider scriva. Il provider scrive in genere un evento se i bit della parola chiave dell'evento corrispondono a uno qualsiasi dei bit impostati in questo valore o se l'evento non ha bit di parole chiave impostati, oltre a soddisfare i criteri Level e MatchAllKeyword .

[in] MatchAllKeyword

Maschera di parole chiave a 64 bit che limita gli eventi che si desidera che il provider scriva. Il provider scrive in genere un evento se i bit della parola chiave dell'evento corrispondono a tutti i bit impostati in questo valore o se l'evento non ha bit di parole chiave impostati, oltre a soddisfare i criteri Level e MatchAnyKeyword .

Questo valore viene spesso impostato su 0.

[in] EnableProperty

Flag che specificano comportamenti speciali che il runtime ETW deve abilitare durante la raccolta di eventi da questo provider. Per abilitare comportamenti speciali, specificare uno o più flag seguenti. In caso contrario, impostare EnableProperty su 0.

[in, optional] EnableFilterDesc

Struttura EVENT_FILTER_DESCRIPTOR che punta ai dati del filtro. Il provider usa questa opzione per filtrare i dati per impedire che gli eventi che non corrispondono ai criteri di filtro vengano scritti nella sessione. Il provider determina il layout dei dati e la modalità di applicazione del filtro ai dati dell'evento. Una sessione può passare un solo filtro al provider.

Una sessione può chiamare la funzione TdhEnumerateProviderFilters per cercare i filtri per i quali un provider ha registrato il supporto.

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_INVALID_PARAMETER

  Una delle seguenti condizioni è vera:

  • ProviderId è NULL.
  • TraceHandle è NULL.

• ERROR_INVALID_FUNCTION

  Non è possibile aggiornare il livello quando il provider non è registrato.

• ERROR_NO_SYSTEM_RESOURCES

  È stato superato il numero di sessioni di traccia che possono abilitare il provider.

• ERROR_ACCESS_DENIED

  Solo gli utenti con privilegi amministrativi, gli utenti nel Performance Log Users gruppo e i servizi in esecuzione come LocalSystem, LocalServiceo NetworkService possono abilitare i provider di eventi a una sessione tra processi. Per concedere a un utente con restrizioni la possibilità di abilitare un provider di eventi, aggiungerli al Performance Log Users gruppo o vedere EventAccessControl.

  Windows XP e Windows 2000: Chiunque può abilitare un provider di eventi.

Commenti

I controller di traccia eventi chiamano questa funzione per configurare i provider di eventi che scrivono eventi nella sessione. Ad esempio, un controller potrebbe chiamare questa funzione per iniziare a raccogliere eventi da un provider, per modificare il livello o le parole chiave degli eventi raccolti da un provider o per interrompere la raccolta di eventi da un provider.

questa funzione è obsoleta. Per altre funzionalità, il nuovo codice deve usare EnableTraceEx2.

Nella maggior parte dei casi, una chiamata a EnableTraceEx può essere convertita in EnableTraceEx2 come indicato di seguito:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    NULL,           // SourceId
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // EnableProperty
    NULL);          // EnableFilterDesc

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // Timeout
    NULL);          // EnableParameters

In scenari più complessi, una chiamata a EnableTraceEx può essere convertita in EnableTraceEx2 come indicato di seguito:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    SourceId,
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    EnableProperty,
    EnableFilterDesc);

// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
    ENABLE_TRACE_PARAMETERS_VERSION_2,
    EnableProperty,
    0,                 // ControlFlags
    SourceId ? *SourceId : GUID_NULL,
    EnableFilterDesc,
    EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,                 // Timeout
    &EnableParameters);

Per altri dettagli sulla semantica della configurazione dei provider per una sessione, vedere la documentazione per EnableTraceEx2.

Requisiti

Vedi anche

StartTrace

EnableTraceEx2