DbgPrintEx-Funktion (wdm.h)

Artikel
02/27/2024

Die DbgPrintEx-Routine sendet eine Zeichenfolge an den Kerneldebugger, wenn die von Ihnen angegebenen Bedingungen erfüllt sind.

Syntax

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

Parameter

[in] ComponentId

Gibt die Komponente an, die diese Routine aufruft. Dies muss eine der Komponentennamenfilter-IDs sein, die in der Headerdatei Dpfilter.h definiert sind. Um zu vermeiden, dass die Ausgabe Ihres Treibers mit der Ausgabe von Windows-Komponenten vermischt wird, sollten Sie für ComponentId nur die folgenden Werte verwenden:

DPFLTR_IHVVIDEO_ID
DPFLTR_IHVAUDIO_ID
DPFLTR_IHVNETWORK_ID
DPFLTR_IHVSTREAMING_ID
DPFLTR_IHVBUS_ID
DPFLTR_IHVDRIVER_ID

[in] Level

Gibt den Schweregrad der gesendeten Nachricht an. Dies kann eine beliebige 32-Bit-Ganzzahl sein. Werte zwischen 0 und 31 (einschließlich) werden anders behandelt als Werte zwischen 32 und 0xFFFFFFFF. Weitere Informationen finden Sie unter Lesen und Filtern von Debugnachrichten.

[in] Format

Gibt einen Zeiger auf die zu druckende Formatzeichenfolge an. Die Formatzeichenfolge unterstützt die meisten Felder der Formatspezifikation im Printf-Format. Die Unicode-Formatcodes (%C, %S, %lc, %ls, %wc, %ws und %wZ) können jedoch nur mit IRQL = PASSIVE_LEVEL verwendet werden. Die DbgPrintEx-Routine unterstützt keinen der Gleitkommatypen (%f, %e, %E, %g, %G, %a oder %A).

...

Gibt Argumente für die Formatzeichenfolge an, wie in printf.

Rückgabewert

Bei erfolgreicher Ausführung gibt DbgPrintEx den NTSTATUS-Code STATUS_SUCCESS zurück. Andernfalls wird der entsprechende Fehlercode zurückgegeben.

Hinweise

Nur Kernelmodustreiber können die DbgPrintEx-Routine aufrufen.

DbgPrint und DbgPrintEx können unter IRQL<=DIRQL aufgerufen werden. Unicode-Formatcodes (%wc und %ws) können jedoch nur unter IRQL = PASSIVE_LEVEL verwendet werden. Da der Debugger interprocess interrupts (IPIs) für die Kommunikation mit anderen Prozessoren verwendet, kann der Aufruf von DbgPrint bei IRQL>DIRQL zu Deadlocks führen.

DbgPrintEx übergibt entweder die angegebene Zeichenfolge an den Kerneldebugger oder führt überhaupt nichts aus, abhängig von den Werten von ComponentId, Level und den entsprechenden Komponentenfiltermasken. Weitere Informationen finden Sie unter Lesen und Filtern von Debugnachrichten.

Sofern dies nicht unbedingt erforderlich ist, sollten Sie keine Zeichenfolge aus Benutzereingaben oder einem anderen Prozess abrufen und an DbgPrintEx übergeben. Wenn Sie eine Zeichenfolge verwenden, die Sie nicht erstellt haben, müssen Sie überprüfen, ob dies eine gültige Formatzeichenfolge ist und dass die Formatcodes der Argumentliste in Typ und Menge entsprechen. Die bewährte Codierungsmethode besteht darin, dass alle Formatzeichenfolgen zur Kompilierzeit statisch und definiert sind.

Es gibt keine Obergrenze für die Größe der Formatzeichenfolge oder die Anzahl der Argumente. Jeder einzelne Aufruf von DbgPrintEx überträgt jedoch nur 512 Byte an Informationen. Es gibt auch eine Beschränkung für die Größe des DbgPrint-Puffers. Weitere Informationen finden Sie unter DbgPrint-Puffer und Debugger .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows XP und höher.
Zielplattform	Universell
Header	wdm.h (wdm.h einschließen)
Bibliothek	NtDll.lib (Benutzermodus); NtosKrnl.lib (Kernelmodus)
DLL	NtDll.dll (Benutzermodus); NtosKrnl.exe (Kernelmodus)
IRQL	<= DIRQL (siehe Abschnitt Kommentare)

Weitere Informationen