Funzione EventRegister (evntprov.h)
Registra un provider di eventi ETW, creando un handle che può essere usato per scrivere eventi ETW.
Sintassi
ULONG EVNTAPI EventRegister(
[in] LPCGUID ProviderId,
[in, optional] PENABLECALLBACK EnableCallback,
[in, optional] PVOID CallbackContext,
[out] PREGHANDLE RegHandle
);
Parametri
[in] ProviderId
GUID che identifica in modo univoco il provider, talvolta denominato GUID di controllo. Deve essere un identificatore stabile in modo che i controller di traccia possano usare il GUID per sottoscrivere gli eventi di questo provider.
[in, optional] EnableCallback
EnableCallback facoltativo che ETW richiamerà quando una sessione di traccia abilita o disabilita questo provider. Usare NULL se non è necessario alcun callback.
[in, optional] CallbackContext
Dati di contesto facoltativi che ETW fornirà quando si richiama EnableCallback. Usare NULL se non è necessario alcun contesto di callback.
[out] RegHandle
Riceve l'handle di registrazione del provider di eventi. L'handle viene usato nelle chiamate successive alle API del provider, ad esempio EventWrite, EventProviderEnabled e EventRegister.
Prima di scaricare o uscire dal provider, liberare l'handle di registrazione del provider chiamando EventUnregister. DLL che scarica senza liberare tutti gli handle del provider registrati può causare l'arresto anomalo del processo.
Valore restituito
Restituisce ERROR_SUCCESS in caso di esito positivo.
Il codice di errore restituito da EventRegister è destinato principalmente all'uso negli scenari di debug e diagnostica. La maggior parte del codice di produzione deve continuare a essere eseguita anche se non è stato possibile registrare un provider ETW, pertanto le build di versione devono in genere ignorare il codice di errore restituito da EventRegister.
Commenti
EventRegister crea un handle che è possibile usare per scrivere eventi ETW tramite EventWrite, EventWriteTransfer o EventWriteEx.
Nota
La maggior parte dei provider di eventi non chiamerà direttamente EventRegister . La maggior parte dei provider di eventi viene invece implementata usando un framework ETW che 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.
La registrazione di un provider di eventi non deve essere confusa con l'installazione del manifesto di un provider di eventi.
- L'API EventRegister esegue la registrazione di un provider di eventi per creare un handle del provider. Si tratta di un'operazione con ambito processo (l'handle è valido solo all'interno del processo). L'handle può essere usato per scrivere eventi ETW. Tutti gli eventi scritti usando l'handle verranno contrassegnati con il ProviderId specificato durante la registrazione del provider. Non è necessario installare un manifesto per scrivere eventi o acquisire tracce ( anche se l'installazione del manifesto potrebbe essere necessaria per decodificare gli eventi del provider o per consentire al provider di lavorare con il registro eventi).
- Lo strumento wevtutil.exe viene usato per installare o disinstallare il manifesto di un provider di eventi. L'installazione di un manifesto del provider di eventi indica che le informazioni dal manifesto vengono registrate nel sistema. Le informazioni registrate sono globali di sistema e vengono mantenute finché il manifesto non viene disinstallato. Le informazioni registrate includono i nomi, i GUID, i canali e i percorsi DLL delle risorse dei provider definiti nel manifesto. Le informazioni del manifesto vengono usate dagli strumenti di decodifica di traccia e dal registro eventi.
La maggior parte dei componenti registrerà il provider di eventi all'inizializzazione dei componenti e annulla la registrazione del provider di eventi all'arresto del componente. Ad esempio, un'applicazione (EXE) potrebbe registrarsi durante l'avvio dell'applicazione e annullare la registrazione durante l'uscita dell'applicazione. Una libreria dinamica (DLL) potrebbe registrarsi durante DllMain il collegamento del processo e potrebbe annullare la registrazione durante DllMain lo scollegamento del processo.
Poiché la traccia eventi è un problema di debug/diagnostica e non è in genere una funzionalità critica dall'applicazione, la maggior parte delle applicazioni retail deve ignorare automaticamente gli errori restituiti da EventRegister. In caso di errore, EventRegister imposterà il parametro RegHandle su zero in modo che gli usi successivi di RegHandle (ad esempio nelle chiamate a EventWrite e EventUnregister) non abbiano alcun effetto.
Ogni processo può registrare fino a 1.024 provider. Tuttavia, è necessario limitare il numero di provider registrati dal componente a uno o due. Questo limite include i provider registrati usando questa funzione e i provider registrati con RegisterTraceGuids.
Prima di Windows Vista: Non esiste alcun limite specifico al numero di provider che un processo può registrare.
Requisiti
| Client minimo supportato | Windows Vista [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2008 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | evntprov.h |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |