IDebugControl：：ControlledOutput 方法（dbgeng.h）

项目
02/06/2025

ControlledOutput 方法格式化字符串，并将结果发送到输出回调，这些回调已注册到某些引擎的客户端。

语法

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

参数

[in] OutputControl

指定一个输出控件，该控件确定哪些客户端的输出回调将接收输出。有关可能的值，请参阅 DEBUG_OUTCTL_XXX。有关输出的详细信息，请参阅输入和输出。

[in] Mask

指定输出类型位字段。有关可能的值，请参阅 DEBUG_OUTPUT_XXX。

[in] Format

指定格式字符串，如 printf中所示。通常，转换字符的工作方式与 C 中的转换字符完全相同。对于浮点转换字符，除非使用 l 修饰符，否则 64 位参数将解释为 32 位浮点数。

支持 %p 转换字符，但它表示目标地址空间中的指针。它可能没有任何修饰符，并且它使用调试器的内部地址格式。支持以下其他转换字符。

字符	参数类型	论点	打印的文本
%p	ULONG64	地址空间中的指针。	指针的值。
%N	DWORD_PTR（32 位或 64 位，具体取决于主机的体系结构）	主机虚拟地址空间中的指针。	指针的值。（这相当于标准 C %p 字符。
%I	ULONG64	任何 64 位值。	指定的值。如果此值大于0xFFFFFFFF，则将其打印为 64 位值;否则，它以 32 位值的形式打印。
%ma	ULONG64	进程虚拟地址空间中以 NULL 结尾的 ASCII 字符串的地址。	指定的字符串。
%mu	ULONG64	进程虚拟地址空间中以 NULL 结尾的 Unicode 字符串的地址。	指定的字符串。
%msa	ULONG64	进程的虚拟地址空间中ANSI_STRING结构的地址。	指定的字符串。
%msu	ULONG64	进程的虚拟地址空间中UNICODE_STRING结构的地址。	指定的字符串。
%y	ULONG64	包含符号信息的项的进程的虚拟地址空间中的地址。	包含指定符号的名称（如果有）的字符串。
%ly	ULONG64	包含符号信息的项的进程的虚拟地址空间中的地址。	包含指定符号的名称（如果有）以及任何可用的源行信息的字符串。

%Y 格式说明符可用于支持调试器标记语言（DML）。有关详细信息，请参阅使用 DML自定义调试器输出。

下表汇总了 %Y 格式说明符的使用。

字符	参数类型	论点	打印的文本
%Y{t}	字符串	发短信	带引号的字符串。如果输出格式（第一个参数）为 DML，则会将文本转换为 DML。
%Y{T}	字符串	发短信	带引号的字符串。无论输出格式如何，都将始终将文本转换为 DML。
%Y{s}	字符串	发短信	无引号字符串。如果输出格式（第一个参数）为 DML，则会将文本转换为 DML。
%Y{S}	字符串	发短信	无引号字符串。无论输出格式如何，都将始终将文本转换为 DML。
%Y{as}	ULONG64	调试器格式化指针	为填充调试器格式化指针字段的高 32 位部分添加空字符串或 9 个字符的间距。额外空间输出 9 个空格，其中包括前 8 个零加上 '字符。
%Y{ps}	ULONG64	调试器格式化指针	为填充调试器格式化指针字段的高 32 位部分添加空字符串或 8 个字符的间距。
%Y{l}	ULONG64	调试器格式化指针	地址为源行信息。

此代码片段演示如何使用 %Y 格式说明符。

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;

}

此示例代码将生成以下输出。

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]

...

指定其他参数，这些参数表示在格式设置过程中要插入到输出中的值。