Função KeRegisterBugCheckCallback (wdm.h)

A rotina KeRegisterBugCheckCallback registra uma rotina BugCheckCallback, que é executada quando o sistema operacional emite um bug marcar.

Sintaxe

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

Parâmetros

[out] CallbackRecord

Ponteiro para um registro de retorno de chamada que foi inicializado anteriormente por KeInitializeCallbackRecord, para o qual o chamador fornece armazenamento nãopagado.

[in] CallbackRoutine

Ponteiro para a função de retorno de chamada KBUGCHECK_CALLBACK_ROUTINE fornecida pelo driver.

[in, optional] Buffer

Ponteiro para um buffer fornecido pelo chamador, que deve estar na memória residente, como pool nãopagado.

[in] Length

Especifica o tamanho em bytes do buffer alocado pelo chamador.

[in] Component

Ponteiro para uma cadeia de caracteres ANSI terminada em nulo que identifica o chamador. Essa cadeia de caracteres geralmente contém o nome do driver do dispositivo ou, possivelmente, de seu dispositivo.

Retornar valor

KeRegisterBugCheckCallback retornará TRUE se a rotina fornecida pelo chamador for adicionada com êxito ao conjunto de retornos de chamada marcar de bug registrados; caso contrário, retornará FALSE.

Comentários

A rotina KeRegisterBugCheckCallback registra uma rotina BugCheckCallback, o tipo mais simples de rotina de retorno de chamada marcar bug.

Para registrar outros tipos de retornos de chamada marcar bug, como as rotinas KbCallbackDumpIo e KbCallbackAddPages, use a rotina KeRegisterBugCheckReasonCallback.

A rotina BugCheckCallback é executada quando o sistema emite um bug marcar. Um driver pode usar a rotina para redefinir o dispositivo para um estado conhecido. Para obter mais informações, consulte BugCheckCallback.

Os drivers podem usar a rotina KeDeregisterBugCheckCallback para remover o retorno de chamada. Qualquer driver que possa ser descarregado deve remover todos os seus retornos de chamada em sua rotina de descarregamento .

A cadeia de caracteres Componente é usada para identificar o driver durante a depuração de despejo de memória. Para exibir os dados de despejo de memória correspondentes a qualquer cadeia de caracteres de componente especificada, você pode usar a extensão do depurador !bugdump . Também é possível depurar o bug marcar própria rotina de retorno de chamada. Para obter informações sobre depuradores e extensões de depurador, consulte Depuração do Windows.

Implementação

Para definir uma rotina de retorno de chamada BugCheckCallback, primeiro você deve fornecer uma declaração de função que identifique o tipo de rotina de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação a encontrar erros.

Por exemplo, para definir uma rotina de retorno de chamada BugCheckCallback chamada MyBugCheckCallback, use o tipo KBUGCHECK_CALLBACK_ROUTINE conforme mostrado neste exemplo de código:

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:

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

O tipo de função KBUGCHECK_CALLBACK_ROUTINE é definido no arquivo de cabeçalho Wdm.h.

Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione o _Use_decl_annotations_ annotation à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função KBUGCHECK_CALLBACK_ROUTINE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Confira também

Gravando uma rotina de retorno de chamada de verificação de bugs.

KeDeregisterBugCheckCallback

KeInitializeCallbackRecord

KeRegisterBugCheckReasonCallback