Fonction vDbgPrintExWithPrefix (wdm.h)

Article
08/08/2023

La routine vDbgPrintExWithPrefix envoie une chaîne au débogueur du noyau si certaines conditions que vous spécifiez sont remplies. Cette routine peut ajouter un préfixe à la sortie du débogueur pour faciliter l’organisation des résultats du débogage.

Syntaxe

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

Paramètres

[in] Prefix

Chaîne ajoutée au début de la sortie du débogueur. Vous pouvez utiliser cette chaîne pour organiser la sortie du débogueur en ajoutant un identificateur unique.

Par exemple, une routine spécifique au composant peut spécifier le nom du composant lorsqu’il appelle vDbgPrintExWithPrefix. Cette routine ajoute automatiquement le nom du composant au début de toute la sortie de débogage passée à la routine d’impression de débogage du composant.

[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 vDbgPrintExWithPrefix ne prend en charge aucun des types à virgule flottante (%f, %e, %E, %g, %G, %a ou %A).

[in] arglist

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

Valeur retournée

vDbgPrintExWithPrefix 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 vDbgPrintExWithPrefix .

vDbgPrintExWithPrefix 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, un appel à vDbgPrintExWithPrefix à IRQL > DIRQL peut provoquer des blocages.

vDbgPrintExWithPrefix transmet la chaîne qu’il cré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 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 à vDbgPrintExWithPrefix. 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 à vDbgPrintExWithPrefix 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

vDbgPrintEx

Partager via