KeRegisterBugCheckCallback-Funktion (wdm.h)

Die KeRegisterBugCheckCallback-Routine registriert eine BugCheckCallback-Routine , die ausgeführt wird, wenn das Betriebssystem eine Fehlerüberprü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

Zeigen Sie 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 ausgelagerter Pool.

[in] Length

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

[in] Component

Zeiger auf eine MIT NULL beendete ANSI-Zeichenfolge, die den Aufrufer identifiziert. Diese Zeichenfolge enthält in der Regel den Namen des Gerätetreibers oder möglicherweise des Geräts. Die Zeichenfolge muss im nicht ausgelagerten Speicher zugewiesen werden, da möglicherweise während der Fehlerüberprüfung auf sie zugegriffen wird, wenn das virtuelle Arbeitsspeichersystem nicht verfügbar ist.

Rückgabewert

KeRegisterBugCheckCallback gibt TRUE zurück, wenn die vom Aufrufer bereitgestellte Routine erfolgreich der Gruppe registrierter Fehlerüberprüfungsrückrufe hinzugefügt wird; andernfalls wird FALSE zurückgegeben.

Bemerkungen

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

Verwenden Sie stattdessen die KeRegisterBugCheckReasonCallback-Routine, um andere Arten von Fehlerüberprüfungsrückrufen wie KbCallbackDumpIo und KbCallbackAddPages zu registrieren.

Die BugCheckCallback Routine wird ausgeführt, wenn das System eine Fehlerüberprü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 Component-Zeichenfolge wird verwendet, um den Treiber während des Absturzabbilddebuggings zu identifizieren. Um die Absturzabbilddaten anzuzeigen, die allen angegebenen Component Zeichenfolge entsprechen, können Sie die !bugdump Debuggererweiterung verwenden. Es ist auch möglich, die Fehlerüberprüfungsrückrufroutine selbst zu debuggen. Informationen zu Debuggern und Debuggererweiterungen finden Sie unter Windows Debugging.

Implementation

Um eine BugCheckCallback-Rückrufroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden.

Um beispielsweise eine BugCheckCallback-Rückrufroutine zu definieren, die den Namen MyBugCheckCallback hat, verwenden Sie den KBUGCHECK_CALLBACK_ROUTINE Typ, 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 wird in wdm.h definiert.

Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations_ Anmerkung hinzufügen. Die Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp KBUGCHECK_CALLBACK_ROUTINE in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.

Anforderungen

Siehe auch

Schreiben einer Fehlerüberprüfungsrückrufroutine

KeDeregisterBugCheckCallback

KeInitializeCallbackRecord

KeRegisterBugCheckReasonCallback