IDebugControl::ControlledOutput-Methode (dbgeng.h)

Artikel
02/06/2025

Die ControlledOutput--Methode formatiert eine Zeichenfolge und sendet das Ergebnis an Ausgaberückrufe, die bei einigen Clients des Moduls registriert wurden.

Syntax

HRESULT ControlledOutput(
  [in] ULONG OutputControl,
  [in] ULONG Mask,
  [in] PCSTR Format,
       ...   
);

Parameter

[in] OutputControl

Gibt ein Ausgabesteuerelement an, das bestimmt, welche Ausgaberückrufe der Clients die Ausgabe erhalten. Mögliche Werte finden Sie unter DEBUG_OUTCTL_XXX. Weitere Informationen zur Ausgabe finden Sie unter Eingabe- und Ausgabe-.

[in] Mask

Gibt das Bitfeld des Ausgabetyps an. Mögliche Werte finden Sie unter DEBUG_OUTPUT_XXX.

[in] Format

Gibt die Formatzeichenfolge wie in printf-an. In der Regel funktionieren Konvertierungszeichen genau wie in C. Für die Gleitkommakonvertierungszeichen wird das 64-Bit-Argument als 32-Bit-Gleitkommazahl interpretiert, es sei denn, der l Modifizierer wird verwendet.

Das %p Konvertierungszeichen wird unterstützt, stellt jedoch einen Zeiger im Adressraum eines Ziels dar. Möglicherweise gibt es keine Modifizierer und verwendet die interne Adressformatierung des Debuggers. Die folgenden zusätzlichen Konvertierungszeichen werden unterstützt.

Zeichen	Argumenttyp	Argument	Gedruckter Text
%p	ULONG64	Zeiger in einem Adressraum.	Der Wert des Zeigers.
%N	DWORD_PTR (32 oder 64 Bit, abhängig von der Architektur des Hosts)	Zeiger im virtuellen Adressbereich des Hosts.	Der Wert des Zeigers. (Dies entspricht dem Standardzeichen C %p.)
%I	ULONG64	Ein beliebiger 64-Bit-Wert.	Der angegebene Wert. Wenn dies größer als 0xFFFFFFFF ist, wird sie als 64-Bit-Wert gedruckt; andernfalls wird sie als 32-Bit-Wert gedruckt.
%ma	ULONG64	Adresse einer MIT NULL beendeten ASCII-Zeichenfolge im virtuellen Adressraum des Prozesses.	Die angegebene Zeichenfolge.
%mu	ULONG64	Adresse einer MIT NULL beendeten Unicode-Zeichenfolge im virtuellen Adressraum des Prozesses.	Die angegebene Zeichenfolge.
%msa	ULONG64	Adresse einer ANSI_STRING Struktur im virtuellen Adressraum des Prozesses.	Die angegebene Zeichenfolge.
%msu	ULONG64	Adresse einer UNICODE_STRING Struktur im virtuellen Adressraum des Prozesses.	Die angegebene Zeichenfolge.
%y	ULONG64	Adresse im virtuellen Adressbereich des Prozesses eines Elements mit Symbolinformationen.	Zeichenfolge, die den Namen des angegebenen Symbols (und Verschiebung, falls vorhanden) enthält.
%ly	ULONG64	Adresse im virtuellen Adressbereich des Prozesses eines Elements mit Symbolinformationen.	Zeichenfolge, die den Namen des angegebenen Symbols (und Verschiebung, falls vorhanden) sowie alle verfügbaren Quellzeileninformationen enthält.

Der %Y Formatbezeichner kann verwendet werden, um die Debugger Markup Language (DML) zu unterstützen. Weitere Informationen finden Sie unter Anpassen der Debuggerausgabe mithilfe von DML-.

In der folgenden Tabelle wird die Verwendung des %Y Formatbezeichners zusammengefasst.

Zeichen	Argumenttyp	Argument	Gedruckter Text
%Y{t}	Schnur	Text	Zeichenfolge in An zitierten Zeichenfolgen. Wandelt Text in DML um, wenn das Ausgabeformat (erste Arg) DML ist.
%Y{T}	Schnur	Text	Zeichenfolge in An zitierten Zeichenfolgen. Wandelt Text unabhängig vom Ausgabeformat immer in DML um.
%Y{s}	Schnur	Text	Nicht angehaltene Zeichenfolge. Wandelt Text in DML um, wenn das Ausgabeformat (erste Arg) DML ist.
%Y{S}	Schnur	Text	Nicht angehaltene Zeichenfolge. Wandelt Text unabhängig vom Ausgabeformat immer in DML um.
%Y{as}-	ULONG64	Debugger formatierter Zeiger	Fügt entweder eine leere Zeichenfolge oder 9 Zeichen des Abstands zum Auffüllen des hohen 32-Bit-Teils des formatierten Debuggerzeigerfelds hinzu. Der zusätzliche Leerraum gibt 9 Leerzeichen aus, die die oberen 8 Nullen und das Zeichen " enthalten.
%Y{ps}-	ULONG64	Debugger formatierter Zeiger	Fügt entweder eine leere Zeichenfolge oder 8 Zeichen des Abstands zum Auffüllen des hohen 32-Bit-Teils des debuggerformatierten Zeigerfelds hinzu.
%Y{l}	ULONG64	Debugger formatierter Zeiger	Adresse als Quellzeileninformationen.

Dieser Codeausschnitt veranschaulicht die Verwendung des %Y Formatbezeichners.

HRESULT CALLBACK testout(_In_ PDEBUG_CLIENT pClient, _In_ PCWSTR /*pwszArgs*/)
{
    HRESULT hr = S_OK;

    ComPtr<IDebugControl4> spControl;
    IfFailedReturn(pClient->QueryInterface(IID_PPV_ARGS(&spControl)));

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{t}: %Y{t}\n", L"Hello <World>");
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{T}: %Y{T}\n", L"Hello <World>");
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{s}: %Y{s}\n", L"Hello <World>");
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{S}: %Y{S}\n", L"Hello <World>");

    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{t}: %Y{t}\n", L"Hello <World>");
    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{T}: %Y{T}\n", L"Hello <World>");
    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{s}: %Y{s}\n", L"Hello <World>");
    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{S}: %Y{S}\n", L"Hello <World>");

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{a}: %Y{a}\n", (ULONG64)0x00007ffa7da163c0);
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{as} 64bit   : '%Y{as}'\n", (ULONG64)0x00007ffa7da163c0);
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{as} 32value : '%Y{as}'\n", (ULONG64)0x1);

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{ps} 64bit   : '%Y{ps}'\n", (ULONG64)0x00007ffa7da163c0);
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{ps} 32value : '%Y{ps}'\n", (ULONG64)0x1);

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{l}: %Y{l}\n", (ULONG64)0x00007ffa7da163c0);

    return hr;

}

Dieser Beispielcode würde die folgende Ausgabe generieren.

0:004> !testout
DML/NORMAL Y{t}: "Hello <World>"
DML/NORMAL Y{T}: "Hello <World>"
DML/NORMAL Y{s}: Hello <World>
DML/NORMAL Y{S}: Hello <World>
TEXT/NORMAL Y{t}: "Hello <World>"
TEXT/NORMAL Y{T}: &quot;Hello <World>&quot;
TEXT/NORMAL Y{s}: Hello <World>
TEXT/NORMAL Y{S}: Hello <World>
DML/NORMAL Y{a}: 00007ffa`7da163c0
DML/NORMAL Y{as} 64bit   : '         '
DML/NORMAL Y{as} 32value : '         '
DML/NORMAL Y{ps} 64bit   : '        '
DML/NORMAL Y{ps} 32value : '        '
DML/NORMAL Y{l}: [d:\th\minkernel\kernelbase\debug.c @ 443]

...

Gibt zusätzliche Parameter an, die Werte darstellen, die während der Formatierung in die Ausgabe eingefügt werden sollen.

Rückgabewert

Diese Methode kann auch Fehlerwerte zurückgeben. Weitere Informationen finden Sie unter Rückgabewerte.

Rückgabecode	Beschreibung
S_OK	Die Methode war erfolgreich.

Bemerkungen

Beim Generieren sehr großer Ausgabezeichenfolgen ist es möglich, die Grenzen des Debuggermoduls oder des Betriebssystems zu erreichen. Beispielsweise verfügen einige Versionen des Debuggermoduls für eine einzelne Ausgabe über ein 16K-Zeichenlimit. Wenn Sie feststellen, dass eine sehr große Ausgabe abgeschnitten wird, müssen Sie ihre Ausgabe möglicherweise in mehrere Anforderungen aufteilen.