KBUGCHECK_CALLBACK_ROUTINE fonction de rappel (wdm.h)

Article
02/07/2025

La routine BugCheckCallback est exécutée chaque fois que le système émet une vérification de bogue.

La fonction de rappel KBUGCHECK_REASON_CALLBACK_ROUTINE offre plus de fonctionnalités que ce rappel plus ancien.

Syntaxe

KBUGCHECK_CALLBACK_ROUTINE KbugcheckCallbackRoutine;

void KbugcheckCallbackRoutine(
  [in] IN PVOID Buffer,
  [in] IN ULONG Length
)
{...}

Paramètres

[in] Buffer

Pointeur vers la mémoire tampon spécifiée lors de l’inscription du rappel.

[in] Length

Spécifie la longueur, en octets, de la mémoire tampon pointée par le paramètre tampon.

Valeur de retour

Aucun

Remarques

Les pilotes peuvent fournir un BugCheckCallback qui réinitialise l’appareil à un état connu si le système émet une vérification de bogue.

Utilisez keRegisterBugCheckCallback pour inscrire une routine BugCheckCallback. Un pilote peut ensuite supprimer le rappel à l’aide de la routine KeDeregisterBugCheckCallback. Si le pilote peut être déchargé, il doit supprimer les rappels inscrits dans son décharger routine.

Une routine BugCheckCallback est fortement limitée dans les actions qu’elle peut entreprendre. Pour plus d’informations, consultez Écriture d’une routine de rappel de vérification des bogues. La routine peut utiliser en toute sécurité leXXXREAD_PORT_, READ_REGISTER_XXX, WRITE_PORT_XXXet WRITE_REGISTER_routines de XXX pour interagir avec l’appareil.

Les pilotes qui nécessitent une interaction plus sophistiquée avec le système, car il émet une vérification des bogues peuvent à la place implémenter des routines KbCallbackDumpIo ou KbCallbackSecondaryDumpData.

Notez qu’à partir des systèmes d’exploitation Windows XP SP1 et Windows Server 2003, BugCheckCallback routines s’exécutent une fois que le fichier de vidage sur incident du système a déjà été écrit. (Sur les versions antérieures de Windows, les routines s’exécutent avant l’écriture du fichier de vidage sur incident.) Ainsi, toutes les données stockées dans la mémoire tampon spécifiée par le paramètre Buffer n’apparaissent pas dans le fichier de vidage sur incident. Les pilotes requis pour écrire des données dans le fichier de vidage sur incident implémentent plutôt une routine KbCallbackSecondaryDumpData. (Sur les versions antérieures de Windows, les données écrites dans tampon apparaissent dans le fichier de vidage sur incident.)

Exemples

Pour définir une routine de rappel BugCheckCallback, vous devez d’abord fournir une déclaration de fonction qui identifie le type de routine de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une routine de rappel BugCheckCallback nommée MyBugCheckCallback, utilisez le type KBUGCHECK_CALLBACK_ROUTINE comme indiqué dans cet exemple de code :

KBUGCHECK_CALLBACK_ROUTINE MyBugCheckCallback;

Ensuite, implémentez votre routine de rappel comme suit :

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

Le type de fonction KBUGCHECK_CALLBACK_ROUTINE est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction KBUGCHECK_CALLBACK_ROUTINE dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur les exigences relatives aux déclarations de fonction, consultez déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur Use_decl_annotations, consultez annoter le comportement de la fonction.