Fonction DbgPrintEx (wdm.h)

Article
02/27/2024

La routine DbgPrintEx envoie une chaîne au débogueur de noyau si les conditions que vous spécifiez sont remplies.

Syntaxe

NTSYSAPI ULONG DbgPrintEx(
  [in] ULONG ComponentId,
  [in] ULONG Level,
  [in] PCSTR Format,
       ...   
);

Paramètres

[in] ComponentId

Spécifie le composant appelant cette routine. Il doit s’agir de l’un des ID de filtre de nom de composant définis dans le fichier d’en-tête Dpfilter.h. Pour éviter de mélanger la sortie de votre pilote avec la sortie des composants Windows, vous devez utiliser uniquement les valeurs suivantes pour ComponentId :

DPFLTR_IHVVIDEO_ID
DPFLTR_IHVAUDIO_ID
DPFLTR_IHVNETWORK_ID
DPFLTR_IHVSTREAMING_ID
DPFLTR_IHVBUS_ID
DPFLTR_IHVDRIVER_ID

[in] Level

Spécifie la gravité du message envoyé. Il peut s’agir de n’importe quel entier 32 bits. Les valeurs comprises entre 0 et 31 (inclus) sont traitées différemment des valeurs comprises entre 32 et 0xFFFFFFFF. Pour plus d’informations, consultez Lecture et filtrage des messages de débogage.

[in] Format

Spécifie un pointeur vers la chaîne de format à imprimer. La chaîne Format prend en charge la plupart des champs de spécification de formatde style printf. Toutefois, les codes de format Unicode (%C, %S, %lc, %ls, %wc, %ws et %wZ) ne peuvent être utilisés qu’avec IRQL = PASSIVE_LEVEL. La routine DbgPrintEx ne prend pas en charge les types à virgule flottante (%f, %e, %E, %g, %G, %a ou %A).

...

Spécifie les arguments de la chaîne de format, comme dans printf.

Valeur retournée

En cas de réussite, DbgPrintEx retourne le code NTSTATUS STATUS_SUCCESS ; sinon, il retourne le code d’erreur approprié.

Remarques

Seuls les pilotes en mode noyau peuvent appeler la routine DbgPrintEx .

DbgPrint et DbgPrintEx peuvent être appelés à l’adresse IRQL<=DIRQL. Toutefois, les codes au format Unicode (%wc et %ws) ne peuvent être utilisés que dans IRQL = PASSIVE_LEVEL. En outre, étant donné que le débogueur utilise des interruptions interprocessus (IPIs) pour communiquer avec d’autres processeurs, l’appel de DbgPrint à IRQL>DIRQL peut provoquer des blocages.

DbgPrintEx transmet la chaîne spécifiée au débogueur du noyau ou ne fait rien du tout, en fonction des valeurs de ComponentId, Level et des masques de filtre de composant correspondants. Pour plus d’informations, consultez Lecture et filtrage des messages de débogage.

Sauf si cela est absolument nécessaire, vous ne devez pas obtenir de chaîne à partir d’une entrée utilisateur ou d’un autre processus et la transmettre à DbgPrintEx. Si vous utilisez une chaîne que vous n’avez pas créée, vous devez vérifier qu’il s’agit d’une chaîne de format valide et que les codes de format correspondent à la liste d’arguments en type et en quantité. La meilleure pratique de codage consiste à ce que toutes les chaînes de format soient statiques et définies au moment de la compilation.

Il n’existe aucune limite supérieure à la taille de la chaîne Format ou au nombre d’arguments. Toutefois, tout appel unique à DbgPrintEx ne transmet que 512 octets d’informations. Il existe également une limite à la taille de la mémoire tampon DbgPrint. Pour plus d’informations, consultez La mémoire tampon DbgPrint et le débogueur .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Microsoft Windows XP et versions ultérieures.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h)
Bibliothèque	NtDll.lib (mode utilisateur) ; NtosKrnl.lib (mode noyau)
DLL	NtDll.dll (mode utilisateur) ; NtosKrnl.exe (mode noyau)
IRQL	<= DIRQL (voir la section Commentaires)

Voir aussi