KeRegisterBugCheckCallback-Funktion (wdm.h)

Artikel
02/27/2024

Die KeRegisterBugCheckCallback-Routine registriert eine BugCheckCallback-Routine , die ausgeführt wird, wenn das Betriebssystem eine Fehlerprüfung ausgibt.

Syntax

BOOLEAN KeRegisterBugCheckCallback(
  [out]          PKBUGCHECK_CALLBACK_RECORD  CallbackRecord,
  [in]           PKBUGCHECK_CALLBACK_ROUTINE CallbackRoutine,
  [in, optional] PVOID                       Buffer,
  [in]           ULONG                       Length,
  [in]           PUCHAR                      Component
);

Parameter

[out] CallbackRecord

Zeiger auf einen Rückrufdatensatz, der zuvor von KeInitializeCallbackRecord initialisiert wurde, für den der Aufrufer nicht ausgelagerten Speicher bereitstellt.

[in] CallbackRoutine

Zeiger auf die vom Treiber bereitgestellte KBUGCHECK_CALLBACK_ROUTINE Rückruffunktion.

[in, optional] Buffer

Zeiger auf einen vom Aufrufer bereitgestellten Puffer, der sich im residenten Speicher befinden muss, z. B. nicht auslagerten Pool.

[in] Length

Gibt die Größe des vom Aufrufer zugewiesenen Puffers in Byte an.

[in] Component

Zeiger auf eine NULL-endende ANSI-Zeichenfolge, die den Aufrufer identifiziert. Diese Zeichenfolge enthält in der Regel den Namen des Gerätetreibers oder möglicherweise des zugehörigen Geräts.

Rückgabewert

KeRegisterBugCheckCallback gibt TRUE zurück, wenn die vom Aufrufer bereitgestellte Routine erfolgreich zu den registrierten Rückrufen für die Fehlerüberprüfung hinzugefügt wurde. Andernfalls wird FALSE zurückgegeben.

Hinweise

Die KeRegisterBugCheckCallback-Routine registriert eine BugCheckCallback-Routine, die einfachste Art von Fehlerüberprüfungs-Rückrufroutine.

Verwenden Sie stattdessen die KeRegisterBugCheckReasonCallback-Routine , um andere Arten von Rückrufen zu registrieren, z. B. KbCallbackDumpIo und KbCallbackAddPages.

Die BugCheckCallback-Routine wird ausgeführt, wenn das System eine Fehlerprüfung ausgibt. Ein Treiber kann die Routine verwenden, um das Gerät auf einen bekannten Zustand zurückzusetzen. Weitere Informationen finden Sie unter BugCheckCallback.

Treiber können die KeDeregisterBugCheckCallback-Routine verwenden, um den Rückruf zu entfernen. Jeder Treiber, der entladen werden kann, muss alle Rückrufe in seiner Unload-Routine entfernen.

Die Komponentenzeichenfolge wird verwendet, um den Treiber während des Absturzabbilddebuggens zu identifizieren. Um die Absturzabbilddaten anzuzeigen, die einer angegebenen Komponentenzeichenfolge entsprechen, können Sie die Debuggererweiterung !bugdump verwenden. Es ist auch möglich, die Rückrufroutine für die Fehlerüberprüfung selbst zu debuggen. Informationen zu Debuggern und Debuggererweiterungen finden Sie unter Windows-Debuggen.

Implementierung

Um eine BugCheckCallback-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier, SDV) und anderen Überprüfungstools, Fehler zu finden.

Um beispielsweise eine BugCheckCallback-Rückrufroutine namens MyBugCheckCheckCallback zu definieren, verwenden Sie den typ KBUGCHECK_CALLBACK_ROUTINE, wie in diesem Codebeispiel gezeigt:

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
VOID
  MyBugCheckCallback(
    PVOID  Buffer,
    ULONG  Length
    )
  {
      // Function body
  }

Der KBUGCHECK_CALLBACK_ROUTINE Funktionstyp ist in der Wdm.h-Headerdatei definiert.

Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen _Use_decl_annotations_ annotation Sie ihrer Funktionsdefinition hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den KBUGCHECK_CALLBACK_ROUTINE Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Beliebige Ebene

Weitere Informationen

Schreiben einer Rückrufroutine für die Fehlerüberprüfung.

KeDeregisterBugCheckCallback

KeInitializeCallbackRecord

KeRegisterBugCheckReasonCallback

Freigeben über