IDebugControl4::ControlledOutputVaListWide 方法 (dbgeng.h)

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

语法

HRESULT ControlledOutputVaListWide(
  [in] ULONG   OutputControl,
  [in] ULONG   Mask,
  [in] PCWSTR  Format,
  [in] va_list Args
);

参数

[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} String 文本 带引号的字符串。 如果输出格式 (第一个参数) 为 DML,则会将文本转换为 DML。
%Y{T} String 文本 带引号的字符串。 无论输出格式如何,始终都会将文本转换为 DML。
%Y{s} String 文本 无引号字符串。 如果输出格式 (第一个参数) 为 DML,则会将文本转换为 DML。
%Y{S} String 文本 无引号字符串。 无论输出格式如何,始终都会将文本转换为 DML。
%Y{as} ULONG64 调试器格式的指针 添加空字符串或 9 个字符的间距,以填充调试器格式化指针字段的高 32 位部分。 额外空间输出 9 个空格,其中包括高 8 个零加上 ' 字符。
%Y{ps} ULONG64 调试器格式的指针 添加空字符串或 8 个字符的间距,以填充调试器格式化指针字段的高 32 位部分。
%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]

[in] Args

指定其他参数,这些参数表示在格式设置期间要插入到输出中的值。 必须使用 va_start 初始化参数。 此方法不调用 va_end

返回值

返回代码 说明
S_OK
方法成功。
 

此方法也可能返回错误值。 有关更多详细信息 ,请参阅返回值

注解

生成非常大的输出字符串时,可能会达到调试器引擎或操作系统的限制。 例如,某些版本的调试器引擎对单个输出有 16K 字符限制。 如果发现非常大的输出被截断,可能需要将输出拆分为多个请求。

va_listva_startva_end宏在 Stdarg.h 中定义。

要求

要求
目标平台 桌面
标头 dbgeng.h (包括 Dbgeng.h、Stdarg.h)

另请参阅

ControlledOutput

IDebugControl4

OutputVaList

dprintf