Funzione di callback PENABLECALLBACK (evntprov.h)
Facoltativamente, i provider di eventi ETW definiscono una funzione EnableCallback per ricevere notifiche di modifica della configurazione. Il tipo PENABLECALLBACK definisce un puntatore a questa funzione di callback. EnableCallback è un segnaposto per il nome della funzione definita dall'applicazione.
Sintassi
PENABLECALLBACK Penablecallback;
void Penablecallback(
[in] LPCGUID SourceId,
[in] ULONG IsEnabled,
[in] UCHAR Level,
[in] ULONGLONG MatchAnyKeyword,
ULONGLONG MatchAllKeyword,
[in, optional] PEVENT_FILTER_DESCRIPTOR FilterData,
[in, optional] PVOID CallbackContext
)
{...}
Parametri
[in] SourceId
GUID specificato dal chiamante che abilita o disabilita il provider.
Il valore deriva dal parametro SourceId di EnableTraceEx o dal campo SourceId del ENABLE_TRACE_PARAMETERS passato a EnableTraceEx2.
Nota
SourceId è il valore della sessione specificata nella chiamata all'API EnableTraceEx o EnableTraceEx2. Può essere o meno uguale al GUID della sessione.
SourceId verrà impostato su GUID_NULL in diversi scenari in cui la notifica non ha un identificatore di origine. Ad esempio, ciò può verificarsi quando una sessione di traccia ha abilitato il provider prima dell'avvio del provider, quando il provider viene arrestato o quando un controller di traccia chiama un'API EnableTrace senza specificare un SourceId.
[in] IsEnabled
Indica il codice di controllo corrispondente a questa notifica. I valori possibili sono i seguenti:
| Valore | Significato |
|---|---|
| EVENT_CONTROL_CODE_DISABLE_PROVIDER (0) | Nessuna sessione ha abilitato il provider. |
| EVENT_CONTROL_CODE_ENABLE_PROVIDER (1) | Una o più sessioni hanno abilitato il provider. |
| EVENT_CONTROL_CODE_CAPTURE_STATE (2) | Una sessione richiede che il provider registri le informazioni sullo stato. Il provider risponderà in genere scrivendo eventi contenenti lo stato del provider. |
Nota
Il valore di IsEnabled potrebbe non essere uguale a ControlCode passato all'API EnableTrace che ha attivato questo evento. Ad esempio, se due sessioni hanno abilitato questo provider e una sessione disabilita questo provider chiamando EnableTraceEx2(..., EVENT_CONTROL_CODE_DISABLE_PROVIDER, ...), il provider riceverà una notifica con IsEnabled impostato su EVENT_CONTROL_CODE_ENABLE_PROVIDER perché il provider è ancora abilitato dall'altra sessione.
Dopo aver ricevuto una notifica di DISABLE_PROVIDER , un provider può ottimizzare le prestazioni disabilitando tutti gli eventi. Dopo aver ricevuto una notifica di ENABLE_PROVIDER , un provider deve abilitare la scrittura di eventi. Può anche ottimizzare le prestazioni registrando i valori dei filtri Level, MatchAnyKeyword e MatchAllKeyword e quindi scrivendo solo gli eventi che superano i filtri (come descritto nelle osservazioni). Dopo aver ricevuto una notifica di CAPTURE_STATE , un provider può eseguire qualsiasi azione appropriata, in genere scrivendo eventi che descrivono la configurazione o lo stato del componente.
Un provider deve ignorare le notifiche con valori IsEnabled che non riconosce o supporta.
[in] Level
Valore che specifica il livello di dettaglio degli eventi che il provider deve scrivere. Quando viene richiamato con il codice di controllo EVENT_CONTROL_CODE_ENABLE_PROVIDER, il provider deve registrare il valore Level e ignorare gli eventi in cui il livello di dettaglio dell'evento è maggiore del livello di livello registrato, ovvero un evento deve essere scritto solo se
eventDescriptor.Level <= recorded.Level
Il livello nella notifica è il massimo dei livelli specificati dai controller di traccia nelle chiamate a EnableTrace, EnableTraceEx o EnableTraceEx2 usando il GUID del provider di eventi. In altre parole, se più sessioni registrano eventi da questo provider di eventi a livelli di dettaglio diversi, il parametro Level per la notifica EnableCallback verrà impostato sul livello più alto (più dettagliato) dei livelli.
[in] MatchAnyKeyword
Valore della maschera di bit che specifica le categorie di eventi che il provider deve scrivere. Quando viene richiamato con il codice di controllo EVENT_CONTROL_CODE_ENABLE_PROVIDER, il provider deve registrare il valore MatchAnyKeyword e dovrebbe successivamente ignorare gli eventi in cui la parola chiave dell'evento è diversa da zero e non ha alcun bit dall'oggetto MatchAnyKeyword registrato, ovvero un evento deve essere scritto solo se
eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAnyKeyword) != 0
MatchAnyKeyword nella notifica è l'unione (OR) delle parole chiave match-any-keywords (abilita flag) specificate dai controller di traccia nelle chiamate a EnableTrace, EnableTraceEx e EnableTraceEx2 per il GUID del provider di eventi. In altre parole, se più sessioni registrano eventi da questo provider di eventi con filtri match-any-keyword diversi, il parametro MatchAnyKeyword per la notifica EnableCallback verrà impostato sul bit per bit-OR dei filtri match-any-keyword delle sessioni.
MatchAllKeyword
Valore della maschera di bit che specifica le categorie di eventi che il provider deve scrivere. Quando si riceve una notifica con il codice di controllo EVENT_CONTROL_CODE_ENABLE_PROVIDER, il provider deve registrare il valore MatchAllKeyword e dovrebbe successivamente ignorare gli eventi in cui la parola chiave dell'evento è diversa da zero e non ha tutti i bit dall'oggetto MatchAllKeyword registrato, ovvero un evento deve essere scritto solo se
eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAllKeyword) == recorded.MatchAllKeyword
MatchAllKeyword nella notifica è la disgiunzione (AND) delle parole chiave match-all-keyword specificate dai controller di traccia nelle chiamate a EnableTraceEx e EnableTraceEx2 per il GUID del provider di eventi. In altre parole, se più sessioni registrano eventi da questo provider di eventi con filtri match-all-keyword diversi, il parametro MatchAllKeyword per la notifica EnableCallback verrà impostato sul bit per bit-AND dei filtri match-all-keyword delle sessioni.
[in, optional] FilterData
Puntatore a un EVENT_FILTER_DESCRIPTOR con dati di filtro per il provider di eventi.
Ogni sessione può specificare un solo filtro. Il descrittore di filtro nella notifica di callback conterrà un filtro da ogni sessione che specifica i dati di filtro durante l'abilitazione del provider.
I dati del filtro sono validi solo all'interno del callback. I provider devono creare una copia locale dei dati se i dati saranno necessari dopo la restituzione del callback.
[in, optional] CallbackContext
Contesto per il callback. Questo è il valore del parametro CallbackContext usato quando il provider di eventi denominato EventRegister.
Valore restituito
nessuno
Osservazioni
I provider di eventi ETW che necessitano di notifiche di modifica della configurazione devono fornire un puntatore all'implementazione enableCallback quando registrano tramite EventRegister. ETW richiamerà la funzione EnableCallback del provider quando viene apportata una modifica alla configurazione di una sessione di traccia che coinvolge il provider. Ad esempio, quando un controller di sessione di traccia configura una traccia tramite EnableTraceEx2 o arresta una traccia tramite ControlTrace, ETW chiamerà la funzione EnableCallback del provider con la configurazione aggiornata risultante.
Nota
La maggior parte dei provider di eventi non implementerà direttamente EnableCallback . La maggior parte dei provider di eventi viene invece implementata usando un framework ETW che fornisce la propria implementazione EnableCallback ed esegue il wrapping delle chiamate a EventRegister, EventWrite e EventUnregister. Ad esempio, è possibile scrivere un manifesto dell'evento e quindi usare il compilatore di messaggi per generare codice C/C++ per gli eventi oppure è possibile usare TraceLogging per evitare la necessità di un manifesto. Il framework ETW implementa in genere una funzione EnableCallback che registra i valori , MatchAnyKeyworde MatchAllKeyword della Levelnotifica e il framework usa automaticamente i valori registrati per filtrare gli eventi. Il framework ETW supporta in genere la chiamata di un callback fornito dall'utente se l'utente richiede la gestione delle notifiche personalizzata. Ad esempio, TraceLoggingProvider.h consente di specificare un callback di notifica tramite TraceLoggingRegisterEx.
Importante
La funzione EnableCallback del provider deve essere il più semplice possibile. Deve registrare le informazioni necessarie e restituire rapidamente. Una funzione di callback a esecuzione prolungata può causare ritardi nelle API del controllo sessione ETW, ad esempio EnableTraceEx2 o ControlTrace. La funzione di callback non deve eseguire alcuna operazione che richiede il blocco del caricatore del processo, ovvero non deve chiamare direttamente o indirettamente LoadLibrary o FreeLibrary. La funzione di callback non deve bloccarsi sui blocchi. La funzione di callback può causare un deadlock se si blocca nei blocchi o se richiama qualsiasi API del controllo sessione ETW, ad esempio StartTrace, ControlTrace o EnableTrace.
Il callback di notifica consente al provider di eventi di eseguire in modo più efficiente perché il provider può eseguire il proprio rilevamento del livello, delle parole chiave e di altri filtri. Tenendo traccia dei filtri, il provider può ignorare in modo efficiente gli eventi non abilitati, ad esempio il provider non deve preparare i dati dell'evento o chiamare EventWrite per gli eventi non necessari per le sessioni di traccia.
Si noti che il rilevamento dei filtri non è necessario per il corretto funzionamento di un provider: ETW fornisce funzioni EventEnabled e EventProviderEnabled che un provider può usare e le API ETW EventWrite ignoreranno automaticamente tutti gli eventi disabilitati. Tuttavia, il rilevamento dei filtri implementato dal provider può essere più efficiente delle chiamate a EventEnabled o EventProviderEnabled.
Il callback delle notifiche consente anche al provider di gestire le richieste di "acquisizione-stato" dalle sessioni di traccia. Le richieste di stato di acquisizione vengono in genere inviate da una sessione di traccia quando inizia la registrazione di eventi da un provider. Se lo stato di acquisizione è supportato da un provider, potrebbe rispondere alla richiesta dello stato di acquisizione registrando informazioni sullo stato, ad esempio informazioni di configurazione o statistiche di riepilogo relative all'operazione del componente prima della richiesta.
Il valore Level che ETW passa al callback è il valore di livello più alto (più dettagliato) specificato per questo provider di eventi da qualsiasi sessione di traccia in esecuzione. Ad esempio, se la sessione A ha abilitato questo provider per gli eventi di avviso (livello 3) e quindi la sessione B abilita il provider per gli eventi critici (livello 1), il valore Di livello per il callback sarà 3, non 1.
Analogamente, i valori MatchAnyKeyword e MatchAllKeyword sono valori compositi calcolati dalla configurazione di tutte le sessioni che hanno abilitato il provider di eventi. MatchAnyKeyword è l'OR delle impostazioni EnableFlags/MatchAnyKeyword delle sessioni. MatchAllKeyword è l'AND delle impostazioni MatchAllKeyword delle sessioni.
Se la funzione EnableCallback del provider ha acquisito lo stato Enabled, Level, MatchAnyKeyword e MatchAllKeyword del provider, il provider può determinare se un evento deve essere scritto usando una funzione simile alla seguente:
BOOL MyProviderEventEnabled(
_In_ const MY_PROVIDER_STATE* pProvider,
_In_ const EVENT_DESCRIPTOR* pEvent)
{
return
pProvider->Enabled &&
pEvent->Level <= pProvider->Level &&
(pEvent->Keyword == 0 || (
(pEvent->Keyword & pProvider->MatchAnyKeyword) != 0 &&
(pEvent->Keyword & pProvider->MatchAllKeyword) == pProvider->MatchAllKeyword
));
}
Requisiti
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | evntprov.h |