Функция KeRegisterBugCheckCallback (wdm.h)

Подпрограмма KeRegisterBugCheckCallback регистрирует подпрограмму BugCheckCallback , которая выполняется при возникновении ошибки в операционной системе.

Синтаксис

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

Указатель на строку ANSI, завершающую значение NULL, которая идентифицирует вызывающий объект. Эта строка обычно содержит имя драйвера устройства или, возможно, его устройства. Строка должна быть выделена в нестраничной памяти, так как она может быть доступна во время проверки ошибок при недоступной системе виртуальной памяти.

Возвращаемое значение

KeRegisterBugCheckCallback возвращает значение TRUE, если подпрограмма, предоставленная вызывающим пользователем, успешно добавлена в набор зарегистрированных обратных вызовов с проверкой ошибок; в противном случае возвращает значение FALSE.

Замечания

Подпрограмма KeRegisterBugCheckCallback регистрирует подпрограмму BugCheckCallback , простейший вид подпрограммы обратного вызова проверки ошибок.

Чтобы зарегистрировать другие виды обратных вызовов ошибок, таких как KbCallbackDumpIo и KbCallbackAddPages , используйте подпрограмму KeRegisterBugCheckReasonCallback .

Подпрограмма BugCheckCallback выполняется, когда система выдает проверку ошибок. Драйвер может использовать подпрограмму для сброса устройства в известное состояние. Дополнительные сведения см. в статье BugCheckCallback.

Драйверы могут использовать подпрограмму KeDeregisterBugCheckCallback для удаления обратного вызова. Любой драйвер, который можно выгрузить, должен удалить все обратные вызовы в подпрограмме выгрузки .

Строка компонента используется для идентификации драйвера во время отладки аварийного дампа. Чтобы отобразить данные аварийного дампа, соответствующие любой указанной строке компонента , можно использовать расширение отладчика !bugdump . Кроме того, можно отлаживать сам подпрограмму обратного вызова проверки ошибок. Сведения об отладчиках и расширениях отладчика см. в разделе "Отладка Windows".

Implementation

Чтобы определить подпрограмму обратного вызова BugCheckCallback , необходимо сначала указать объявление функции, определяющее тип определяемой процедуры обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средства проверки статических драйверов (SDV) и других средств проверки подлинности найти ошибки.

Например, чтобы определить подпрограмму обратного вызова BugCheckCallback с именем MyBugCheckCallback, используйте тип 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_ в определение функции. Заметка Use_decl_annotations_ гарантирует, что используются заметки, применяемые к типу функции KBUGCHECK_CALLBACK_ROUTINE в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе "Объявление функций с помощью типов ролей функций для драйверов WDM". Сведения о Use_decl_annotations см. в разделе " Поведение функции аннотирования".

Требования

См. также

Написание процедуры обратного вызова проверки ошибок

KeDeregisterBugCheckCallback

KeInitializeCallbackRecord

KeRegisterBugCheckReasonCallback