Funzione EtwRegister (wdm.h)

Articolo
08/08/2023

La funzione EtwRegister registra il provider di eventi e deve essere chiamata prima che un provider possa avviare la traccia. La funzione EtwRegister è la controparte della modalità kernel alla funzione EventRegister in modalità utente. La funzione può anche fornire un puntatore a una funzione di callback facoltativa che può essere usata per fornire funzionalità di filtro eventi aggiuntive.

Sintassi

NTSTATUS EtwRegister(
  [in]           LPCGUID            ProviderId,
  [in, optional] PETWENABLECALLBACK EnableCallback,
  [in, optional] PVOID              CallbackContext,
  [out]          PREGHANDLE         RegHandle
);

Parametri

[in] ProviderId

Puntatore al GUID del provider di eventi.

[in, optional] EnableCallback

Puntatore a una funzione di callback facoltativa. La funzione di callback offre funzionalità aggiuntive di filtro eventi. La funzione di callback è definita dall'utente.

[in, optional] CallbackContext

La funzione passa il contesto di callback facoltativo quando viene eseguito un callback. È possibile specificare il contesto facoltativo quando si registra un provider. Il parametro CallbackContext supporta gli scenari in cui un callback è condiviso da più provider, come in una classe C++. CallbackContext consente di distinguere le istanze del provider di destinazione per il callback di abilitazione.

[out] RegHandle

Puntatore a una variabile che riceve l'handle di registrazione del provider se la chiamata alla funzione ha esito positivo.

Valore restituito

La funzione EtwRegister restituisce un codice di stato dall'elenco seguente:

Codice restituito	Descrizione
STATUS_SUCCESS	Indica che il provider di eventi è stato registrato correttamente con ETW.
STATUS_INVALID_PARAMETER	Indica che il parametro non è stato valido.
STATUS_Xxx	Indica che la richiesta non è riuscita per il motivo specificato dal valore NTSTATUS. Per informazioni dettagliate sul codice restituito dello stato effettivo, vedere Ntstatus.h.

Commenti

Prima che un driver in modalità kernel possa tracciare gli eventi, il driver deve registrare come provider di eventi usando la funzione EtwRegister . Quando un driver in modalità kernel chiama EtwRegister, la funzione restituisce un handle di registrazione. Questo handle di registrazione può essere usato per testare se una parola chiave o un livello è abilitato per un provider specifico e per chiamare le funzioni di traccia e registrazione degli eventi. Al termine della traccia, un driver deve chiamare la funzione EtwUnregister per annullare la registrazione del provider. Per ogni chiamata a EtwRegister deve essere presente una chiamata corrispondente a EtwUnregister. L'errore di annullare la registrazione del provider di eventi può causare errori quando il processo viene scaricato perché le funzioni di callback associate al processo non sono più valide. Nessuna chiamata di traccia deve essere effettuata all'esterno del codice associato alle funzioni EtwRegister e EtwUnregister. Per ottenere prestazioni ottimali, è possibile chiamare la funzione EtwRegister nella routine DriverEntry e nella funzione EtwUnregister nella routine DriverUnload.

I chiamanti di EtwRegister devono essere in esecuzione in IRQL = PASSIVE_LEVEL nel contesto di un thread di sistema.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows Vista e versioni successive di Windows.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

Vedi anche

EtwUnregister

Condividi tramite