KeRegisterBugCheckCallback 函数 (wdm.h)

  • 项目

KeRegisterBugCheckCallback 例程注册 BugCheckCallback 例程，该例程在操作系统发出 bug 检查时执行。

语法

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

参数

[out] CallbackRecord

指向以前由 KeInitializeCallbackRecord 初始化的回调记录的指针，调用方为其提供非分页存储。

[in] CallbackRoutine

指向驱动程序提供的 KBUGCHECK_CALLBACK_ROUTINE回调函数的指针。

[in, optional] Buffer

指向调用方提供的缓冲区的指针，该缓冲区必须位于驻留内存中，例如非分页池。

[in] Length

指定调用方分配的缓冲区的大小（以字节为单位）。

[in] Component

指向以 null 结尾的 ANSI 字符串的指针，该字符串标识调用方。 此字符串通常包含设备驱动程序的名称，也可能包含其设备的名称。

返回值

如果调用方提供的例程成功添加到注册的 bug-检查回调集，则 KeRegisterBugCheckCallback 返回 TRUE;否则返回 FALSE。

注解

KeRegisterBugCheckCallback 例程注册 BugCheckCallback 例程，这是最简单的 bug 检查回调例程。

若要注册其他类型的 bug 检查回调（如 KbCallbackDumpIo 和 KbCallbackAddPages 例程），请改用 KeRegisterBugCheckReasonCallback 例程。

当系统发出 bug 检查时，将执行 BugCheckCallback 例程。 驱动程序可以使用 例程将设备重置为已知状态。 有关详细信息，请参阅 BugCheckCallback。

驱动程序可以使用 KeDeregisterBugCheckCallback 例程删除回调。 任何可以卸载的驱动程序都必须删除其 Unload 例程中的所有回调。

组件字符串用于在故障转储调试期间标识驱动程序。 若要显示与任何指定的 组件 字符串对应的故障转储数据，可以使用 ！bugdump 调试器扩展。 还可以调试 bug 检查回调例程本身。 有关调试器和调试器扩展的信息，请参阅 Windows 调试。

实现

若要定义 BugCheckCallback 回调例程，必须首先提供一个函数声明，用于标识要定义的回调例程的类型。 Windows 为驱动程序提供一组回调函数类型。 使用回调函数类型声明函数有助于驱动程序代码分析、静态驱动程序验证程序 (SDV) 以及其他验证工具查找错误。

例如，若要定义名为 MyBugCheckCallback 的 BugCheckCallback 回调例程，请使用KBUGCHECK_CALLBACK_ROUTINE类型，如以下代码示例所示：

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

然后，按如下所示实现回调例程：

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

KBUGCHECK_CALLBACK_ROUTINE函数类型在 Wdm.h 头文件中定义。

若要在运行代码分析工具时更准确地识别错误，请务必将 添加到 _Use_decl_annotations_ annotation 函数定义。 Use_decl_annotations批注可确保使用应用于头文件中KBUGCHECK_CALLBACK_ROUTINE函数类型的注释。 有关函数声明要求的详细信息，请参阅 使用 WDM 驱动程序的函数角色类型声明函数。 有关 Use_decl_annotations的信息，请参阅 批注函数行为。

要求

要求 值
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL 任何级别

另请参阅

编写 Bug 检查回调例程。

KeDeregisterBugCheckCallback

KeInitializeCallbackRecord

KeRegisterBugCheckReasonCallback