Fonction vDbgPrintEx (wdm.h)

Article
02/29/2024

La routine vDbgPrintEx envoie une chaîne au débogueur de noyau si certaines conditions sont remplies.

Syntaxe

NTSYSAPI ULONG vDbgPrintEx(
  [in] ULONG   ComponentId,
  [in] ULONG   Level,
  [in] PCCH    Format,
  [in] va_list arglist
);

Paramètres

[in] ComponentId

Composant qui appelle cette routine. Ce paramètre doit être l’un des ID de filtre de nom de composant qui sont définis dans 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

Gravité du message envoyé. Ce paramètre peut être 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 sur la façon dont les valeurs sont traitées, consultez Lecture et filtrage des messages de débogage.

[in] Format

Pointeur vers la chaîne de format à imprimer. La chaîne Format prend en charge la plupart des codes de mise en forme de style printf. Toutefois, vous pouvez utiliser les codes au format Unicode (%C, %S, %lc, %ls, %wc, %ws et %wZ) uniquement avec IRQL = PASSIVE_LEVEL. La routine vDbgPrintEx ne prend pas en charge les types à virgule flottante (%f, %e, %E, %G,%a ou %A).

[in] arglist

Liste d’arguments pour la chaîne de format. La routine vDbgPrintEx utilise cette liste de la même manière que vprintf .

Valeur retournée

vDbgPrintEx retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette routine retourne le code d’erreur approprié.

Remarques

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

vDbgPrintEx peut être appelé à l’adresse IRQL <= DIRQL. Toutefois, vous pouvez utiliser des codes au format Unicode (%wc et %ws) uniquement 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 vDbgPrintEx à IRQL > DIRQL peut provoquer des blocages.

vDbgPrintEx transmet la chaîne qu’il crée au débogueur de noyau ou ne fait rien du tout, en fonction des valeurs ComponentId, Level et des masques de filtre de composant correspondants. Pour plus d’informations sur ce que fait vDbgPrintEx , 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 à vDbgPrintEx. Si vous utilisez une chaîne que vous n’avez pas créée, vous devez vérifier que cette chaîne est 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 dans la liste arglist . Toutefois, tout appel unique à vDbgPrintEx ne transmet que 512 octets d’informations.

Il existe également une limite à la taille de la mémoire tampon utilisée par le débogueur. Pour plus d’informations sur cette limite, consultez La mémoire tampon DbgPrint et le débogueur.

Cette routine est définie dans Wdm.h. Les ID de filtre de composant sont définis dans Dpfilter.h.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Microsoft Windows XP et versions ultérieures du système d’exploitation.
Plateforme cible	Universal
En-tête	wdm.h (include Dpfilter.h, Wdm.h, Ntddk.h, Ndis.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

DbgPrintEx

Partager via