vDbgPrintEx-Funktion (wdm.h)

  • Artikel

Die vDbgPrintEx-Routine sendet eine Zeichenfolge an den Kerneldebugger, wenn bestimmte Bedingungen erfüllt sind.

Syntax

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

Parameter

[in] ComponentId

Die Komponente, die diese Routine aufruft. Dieser Parameter muss eine der Komponentennamenfilter-IDs sein, die in 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

Der Schweregrad der gesendeten Nachricht. Dieser Parameter 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 zur Behandlung der Werte finden Sie unter Lesen und Filtern von Debugnachrichten.

[in] Format

Ein Zeiger auf die zu druckende Formatzeichenfolge. Die Formatzeichenfolge unterstützt die meisten Formatierungscodes im Printf-Stil. Sie können die Unicode-Formatcodes (%C, %S, %lc, %ls, %wc, %ws und %wZ) jedoch nur mit IRQL = PASSIVE_LEVEL verwenden. Die vDbgPrintEx-Routine unterstützt keinen der Gleitkommatypen (%f, %e, %E, %g, %G, %a oder %A).

[in] arglist

Eine Argumentliste für die Formatzeichenfolge. Die vDbgPrintEx-Routine verwendet diese Liste auf die gleiche Weise wie vprintf .

Rückgabewert

vDbgPrintEx gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Routine den entsprechenden Fehlercode zurück.

Hinweise

Nur Kernelmodustreiber können die vDbgPrintEx-Routine aufrufen.

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

vDbgPrintEx übergibt entweder die Zeichenfolge, die erstellt wird, an den Kerneldebugger oder führt in Abhängigkeit von den Werten von ComponentId, Level und den entsprechenden Komponentenfiltermasken gar nichts aus. Weitere Informationen zur Funktionsweise von vDbgPrintEx 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 vDbgPrintEx übergeben. Wenn Sie eine Zeichenfolge verwenden, die Sie nicht erstellt haben, müssen Sie überprüfen, ob diese Zeichenfolge 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 in der Arglistliste . Jeder einzelne Aufruf von vDbgPrintEx überträgt jedoch nur 512 Byte an Informationen.

Es gibt auch eine Beschränkung für die Größe des Puffers, den der Debugger verwendet. Weitere Informationen zu diesem Grenzwert finden Sie unter Der DbgPrint-Puffer und der Debugger.

Diese Routine ist in Wdm.h definiert. Komponentenfilter-IDs werden in Dpfilter.h definiert.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Microsoft Windows XP und höheren Betriebssystemversionen.
Zielplattform Universell
Header wdm.h (include Dpfilter.h, Wdm.h, Ntddk.h, Ndis.h)
Bibliothek NtDll.lib (Benutzermodus); NtosKrnl.lib (Kernelmodus)
DLL NtDll.dll (Benutzermodus); NtosKrnl.exe (Kernelmodus)
IRQL <= DIRQL (siehe Abschnitt Kommentare)

Weitere Informationen

DbgPrintEx