EtwRegister-Funktion (wdm.h)

  • Artikel

Die EtwRegister-Funktion registriert den Ereignisanbieter und muss aufgerufen werden, bevor ein Anbieter mit der Ablaufverfolgung beginnen kann. Die EtwRegister-Funktion ist das Kernelmodus-Pendant zur EventRegister-Funktion des Benutzermodus. Die Funktion kann auch einen Zeiger auf eine optionale Rückruffunktion bereitstellen, die verwendet werden kann, um zusätzliche Funktionen zur Ereignisfilterung bereitzustellen.

Syntax

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

Parameter

[in] ProviderId

Ein Zeiger auf die Ereignisanbieter-GUID.

[in, optional] EnableCallback

Ein Zeiger auf eine optionale Rückruffunktion. Die Rückruffunktion bietet zusätzliche Funktionen zur Ereignisfilterung. Die Rückruffunktion ist benutzerdefinierter.

[in, optional] CallbackContext

Die Funktion übergibt den optionalen Rückrufkontext, wenn ein Rückruf erfolgt. Sie können den optionalen Kontext angeben, wenn Sie einen Anbieter registrieren. Der Parameter CallbackContext unterstützt die Szenarien, in denen ein Rückruf von mehreren Anbietern gemeinsam genutzt wird, wie in einer C++-Klasse. CallbackContext bietet eine Möglichkeit, die Zielanbieterinstanzen für den Aktivierungsrückruf zu unterscheiden.

[out] RegHandle

Ein Zeiger auf eine Variable, die das Anbieterregistrierungshandle empfängt, wenn der Funktionsaufruf erfolgreich ist.

Rückgabewert

Die EtwRegister-Funktion gibt einen status Code aus der folgenden Liste zurück:

Rückgabecode Beschreibung
STATUS_SUCCESS
Gibt an, dass der Ereignisanbieter erfolgreich bei ETW registriert wurde.
STATUS_INVALID_PARAMETER
Gibt an, dass der Parameter ungültig war.
STATUS_Xxx
Gibt an, dass die Anforderung aus dem durch den NTSTATUS-Wert angegebenen Grund fehlgeschlagen ist. Ausführliche Informationen zum tatsächlichen status Rückgabecode finden Sie unter Ntstatus.h.

Hinweise

Bevor ein Kernelmodustreiber Ereignisse nachverfolgen kann, muss sich der Treiber mit der EtwRegister-Funktion als Ereignisanbieter registrieren. Wenn ein Kernelmodustreiber EtwRegister aufruft, gibt die Funktion ein Registrierungshandle zurück. Dieses Registrierungshandle kann verwendet werden, um zu testen, ob ein Schlüsselwort (keyword) oder eine Ebene für einen bestimmten Anbieter aktiviert ist, und um Ereignisablaufverfolgungs- und Protokollierungsfunktionen aufzurufen. Nach Abschluss der Ablaufverfolgung muss ein Treiber die EtwUnregister-Funktion aufrufen, um die Registrierung des Anbieters aufzuheben. Für jeden Aufruf von EtwRegister muss ein entsprechender Aufruf von EtwUnregister vorhanden sein. Wenn die Registrierung des Ereignisanbieters nicht aufgehoben wird, kann dies zu Fehlern führen, wenn der Prozess entladen wird, da die dem Prozess zugeordneten Rückruffunktionen nicht mehr gültig sind. Es sollten keine Ablaufverfolgungsaufrufe ausgeführt werden, die außerhalb des Codes liegen, der durch die Funktionen EtwRegister und EtwUnregister begrenzt ist. Um eine optimale Leistung zu erzielen, können Sie die EtwRegister-Funktion in Ihrer DriverEntry-Routine und die EtwUnregister-Funktion in Ihrer DriverUnload-Routine aufrufen.

Aufrufer von EtwRegister müssen unter IRQL = PASSIVE_LEVEL im Kontext eines Systemthreads ausgeführt werden.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Windows Vista und späteren Windows-Versionen.
Zielplattform Universell
Header wdm.h (include Wdm.h, Ntddk.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI-Complianceregeln HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Weitere Informationen

EtwUnregister