KeRegisterBugCheckCallback function (wdm.h)
The KeRegisterBugCheckCallback routine registers a BugCheckCallback routine, which executes when the operating system issues a bug check.
Syntax
BOOLEAN KeRegisterBugCheckCallback(
[out] PKBUGCHECK_CALLBACK_RECORD CallbackRecord,
[in] PKBUGCHECK_CALLBACK_ROUTINE CallbackRoutine,
[in, optional] PVOID Buffer,
[in] ULONG Length,
[in] PUCHAR Component
);
Parameters
[out] CallbackRecord
Pointer to a callback record that was previously initialized by KeInitializeCallbackRecord, for which the caller provides nonpaged storage.
[in] CallbackRoutine
Pointer to the driver-supplied KBUGCHECK_CALLBACK_ROUTINE callback function.
[in, optional] Buffer
Pointer to a caller-supplied buffer, which must be in resident memory, such as nonpaged pool.
[in] Length
Specifies the size in bytes of the caller-allocated buffer.
[in] Component
Pointer to a null-terminated ANSI string that identifies the caller. This string usually contains the name of the device driver, or possibly of its device.
Return value
KeRegisterBugCheckCallback returns TRUE if the caller-supplied routine is successfully added to the set of registered bug-check callbacks; otherwise, it returns FALSE.
Remarks
The KeRegisterBugCheckCallback routine registers a BugCheckCallback routine, the simplest kind of bug-check callback routine.
To register other kinds of bug-check callbacks, such as KbCallbackDumpIo and KbCallbackAddPages routines, use the KeRegisterBugCheckReasonCallback routine instead.
The BugCheckCallback routine is executed when the system issues a bug check. A driver can use the routine to reset the device to a known state. For more information, see BugCheckCallback.
Drivers can use the KeDeregisterBugCheckCallback routine to remove the callback. Any driver that can be unloaded must remove all of its callbacks in its Unload routine.
The Component string is used to identify the driver during crash-dump debugging. To display the crash dump data corresponding to any specified Component string, you can use the !bugdump debugger extension. It is also possible to debug the bug check callback routine itself. For information about debuggers and debugger extensions, see Windows Debugging.
Implementation
To define a BugCheckCallback callback routine, you must first provide a function declaration that identifies the type of callback routine you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors.
For example, to define a BugCheckCallback callback routine that is named MyBugCheckCallback, use the KBUGCHECK_CALLBACK_ROUTINE type as shown in this code example:
KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;
Then, implement your callback routine as follows:
_Use_decl_annotations_
VOID
MyBugCheckCallback(
PVOID Buffer,
ULONG Length
)
{
// Function body
}
The KBUGCHECK_CALLBACK_ROUTINE function type is defined in the Wdm.h header file.
To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the KBUGCHECK_CALLBACK_ROUTINE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for WDM Drivers. For information about Use_decl_annotations, see Annotating Function Behavior.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 2000. |
| Target Platform | Universal |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | Any level |