vDbgPrintExWithPrefix-Funktion (wdm.h)
Die vDbgPrintExWithPrefix-Routine sendet eine Zeichenfolge an den Kerneldebugger, wenn bestimmte von Ihnen angegebene Bedingungen erfüllt sind. Diese Routine kann ein Präfix an die Debuggerausgabe anfügen, um Debugergebnisse zu organisieren.
Syntax
NTSYSAPI ULONG vDbgPrintExWithPrefix(
[in] PCCH Prefix,
[in] ULONG ComponentId,
[in] ULONG Level,
[in] PCCH Format,
[in] va_list arglist
);
Parameter
[in] Prefix
Eine Zeichenfolge, die am Anfang der Debuggerausgabe angefügt wird. Sie können diese Zeichenfolge verwenden, um die Debuggerausgabe zu organisieren, indem Sie einen eindeutigen Bezeichner hinzufügen.
Beispielsweise könnte eine komponentenspezifische Routine den Namen der Komponente angeben, wenn sie vDbgPrintExWithPrefix aufruft. Diese Routine würde den Komponentennamen automatisch am Anfang aller Debugausgaben hinzufügen, die an die Debugdruckroutine der Komponente übergeben wird.
[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 nur die folgenden Werte für ComponentId 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 jedoch die Unicode-Formatcodes (%C, %S, %lc, %ls, %wc, %ws und %wZ) nur mit IRQL = PASSIVE_LEVEL verwenden. Die vDbgPrintExWithPrefix-Routine unterstützt keinen der Gleitkommatypen (%f, %e, %E, %g, %G, %a oder %A).
[in] arglist
Eine Argumentliste für die Formatzeichenfolge. Die vDbgPrintExWithPrefix-Routine verwendet diese Liste auf die gleiche Weise wie vprintf .
Rückgabewert
vDbgPrintExWithPrefix 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 vDbgPrintExWithPrefix-Routine aufrufen.
vDbgPrintExWithPrefix kann unter IRQL <= DIRQL aufgerufen werden. Sie können unicode-Formatcodes (%wc und %ws) jedoch nur bei IRQL = PASSIVE_LEVEL verwenden. Außerdem kann ein Aufruf von vDbgPrintExWithPrefix bei IRQL > DIRQL zu Deadlocks führen, da der Debugger Interprocess Interrupts (IPIs) für die Kommunikation mit anderen Prozessoren verwendet.
vDbgPrintExWithPrefix übergibt entweder die Zeichenfolge, die es erstellt, an den Kerneldebugger oder tut nichts, abhängig von den Werten von ComponentId, Level und den entsprechenden Komponentenfiltermasken. 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 einer Benutzereingabe oder einem anderen Prozess abrufen und an vDbgPrintExWithPrefix übergeben. Wenn Sie eine Zeichenfolge verwenden, die Sie nicht erstellt haben, müssen Sie überprüfen, ob es sich bei dieser Zeichenfolge um eine gültige Formatzeichenfolge handelt und dass die Formatcodes mit der Argumentliste in Typ und Menge übereinstimmen. 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 vDbgPrintExWithPrefix überträgt jedoch nur 512 Bytes an Informationen.
Es gibt auch eine Begrenzung 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 wird 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) |