Funzione TraceLoggingRegister (traceloggingprovider.h)

Articolo
08/26/2023

Registra un provider TraceLogging in modo che possa essere usato per registrare gli eventi. La registrazione è valida fino a quando il provider non viene registrato o il processo viene chiuso.

Sintassi

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

Parametri

hProvider

Handle del provider TraceLogging da registrare. L'handle non deve essere già registrato.

Valore restituito

Se si chiama questa funzione dal codice in modalità utente, la funzione restituisce un HRESULToggetto . Usare la macro per determinare se la SUCCEEDED() funzione ha esito positivo.

Se si chiama questa funzione dal codice in modalità kernel, la funzione restituisce un NTSTATUSoggetto . Usare la macro per determinare se la NT_SUCCESS() funzione ha esito positivo.

Nota

Il codice di errore restituito da TraceLoggingRegister è principalmente destinato all'uso negli scenari di debug e diagnostica. La maggior parte del codice di produzione deve continuare a essere eseguita anche se un provider ETW non è riuscito a registrare, pertanto le compilazioni di versione devono in genere ignorare il codice di errore restituito da TraceLoggingRegister.

Commenti

Quando un componente viene avviato in esecuzione, qualsiasi handle del provider TraceLogging nel componente verrà ignorato in modo non registrato e tutti i tentativi di usare l'handle del provider per generare eventi verranno ignorati in modo automatico. Prima che il provider possa scrivere eventi, è necessario registrare il provider usando TraceLoggingRegister. Questa operazione verrà in genere eseguita durante l'avvio del componente, ad esempio in main, , DllMain(DLL_PROCESS_ATTACH)wmainWinMain, o DriverEntry. All'arresto del componente annullare la registrazione del provider chiamando TraceLoggingUnregister.

Non chiamare TraceLoggingRegister in un handle del provider già registrato. È possibile annullare la registrazione di un handle e quindi registrarla di nuovo se necessario, anche se ripetutamente registrare e annullare la registrazione del handle possono causare problemi di prestazioni e devono essere evitati (ad esempio, non registrare, scrivere alcuni eventi e quindi annullare la registrazione; registrare una volta all'avvio del componente e annullare la registrazione all'arresto del componente).

TraceLoggingRegister non è thread-safe rispetto ad altre chiamate a TraceLoggingRegister o TraceLoggingUnregister nello stesso handle. Non chiamare TraceLoggingRegister se è possibile che un altro thread possa chiamare TraceLoggingRegister o TraceLoggingUnregister nello stesso handle contemporaneamente.

Se TraceLoggingRegister ha esito negativo, l'handle del provider rimarrà non registrato e tutti gli usi dell'handle del provider saranno senza operazioni sicure. In particolare, è un no-op sicuro per chiamare TraceLoggingWrite o TraceLoggingUnregister con un handle provider non registrato.

Importante

Se la DLL o il driver chiama TraceLoggingRegister in un handle del provider, deve chiamare TraceLoggingUnregister in tale provider prima del caricamento della DLL o del driver. Se una DLL viene scaricata senza chiamare TraceLoggingUnregister, il processo potrebbe successivamente arrestare l'arresto anomalo. Se un driver scarica senza chiamare TraceLoggingUnregister, il sistema potrebbe successivamente arrestare l'arresto anomalo. La funzione TraceLoggingRegister stabilisce un callback di configurazione ETW e TraceLoggingUnregister annulla il callback. Se il callback non viene annullato e il modulo scarica, si verificherà un arresto anomalo della prossima volta che ETW tenta di richiamare il callback.

Avviso

Se il driver chiama TraceLoggingRegister e quindi rileva un errore durante DriverEntry, deve chiamare TraceLoggingUnregister prima di restituire l'errore da DriverEntry. Le normali routine di pulizia del driver non verranno chiamate se il driver restituisce un errore da DriverEntry e l'errore di chiamare TraceLoggingUnregister causerà l'arresto anomalo del sistema.

TraceLoggingRegister esegue le operazioni seguenti:

Chiama EventRegister per aprire la connessione a ETW.
Se EventRegister ha esito positivo, chiama TraceLoggingSetInformation con InformationClassEventProviderSetTraits per configurare il provider per il supporto di TraceLogging.

Una chiamata a TraceLoggingRegister è uguale a una chiamata a TraceLoggingRegisterEx con NULL per i parametri di callback e contesto . Usare TraceLoggingRegisterEx se è necessario ricevere un callback ETW quando le sessioni abilitano o disabilitano il provider.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Intestazione	traceloggingprovider.h
Libreria	Advapi32.lib