KeRegisterBugCheckReasonCallback function (wdm.h)

Article
02/22/2024

The KeRegisterBugCheckReasonCallback function registers a callback routine that executes when the operating system issues a bug check.

Syntax

BOOLEAN KeRegisterBugCheckReasonCallback(
  [out] PKBUGCHECK_REASON_CALLBACK_RECORD  CallbackRecord,
  [in]  PKBUGCHECK_REASON_CALLBACK_ROUTINE CallbackRoutine,
  [in]  KBUGCHECK_CALLBACK_REASON          Reason,
  [in]  PUCHAR                             Component
);

Parameters

[out] CallbackRecord

A pointer to a KBUGCHECK_REASON_CALLBACK_RECORD structure that was initialized by a call to the KeInitializeCallbackRecord routine described in the Windows kernel macros.

[in] CallbackRoutine

A pointer to a callback routine of type KBUGCHECK_REASON_CALLBACK_ROUTINE to register. For information about how to implement this callback routine, see Writing a Bug Check Callback Routine.

[in] Reason

An enumeration of type KBUGCHECK_CALLBACK_REASON that specifies the type of callback routine that CallbackRoutine points to.

[in] Component

A pointer to a null-terminated ANSI string that identifies the caller. For example, you can select a string that describes the device driver, or that contains the device name. You can use the !bugdump debugger extension to display the crash dump data that is associated with this string.

Return value

KeRegisterBugCheckReasonCallback returns TRUE if the callback routine is successfully registered; otherwise, it returns FALSE.

Remarks

Drivers can use KeRegisterBugCheckReasonCallback to register routines that execute during a system bug check.

For descriptions of each type of callback, see KBUGCHECK_CALLBACK_REASON.

Drivers can use the KeDeregisterBugCheckReasonCallback routine to remove the bug check callback registration. Any driver that can be unloaded must remove the registrations of all of its callbacks in its Unload routine.

For information about how to implement these callback routines, see Writing a Bug Check Callback Routine.

To display secondary dump data, you can use the IDebugDataSpaces3::ReadTagged** method in a debugger extension. Another option is to debug the bug check callback routine itself. For more information about debuggers and debugger extensions, see Windows Debugging.

Requirements

Requirement	Value
Minimum supported client	Available in Windows XP Service Pack 1 (SP1), Windows Server 2003, and later versions of Windows.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Any level