Метод IDebugControl4::ControlledOutputWide (dbgeng.h)

Статья
08/07/2023

Метод ControlledOutputWide форматирует строку и отправляет результат в выходные обратные вызовы, зарегистрированные в некоторых клиентах подсистемы.

Синтаксис

HRESULT ControlledOutputWide(
  [in] ULONG  OutputControl,
  [in] ULONG  Mask,
  [in] PCWSTR Format,
       ...    
);

Параметры

[in] OutputControl

Указывает элемент управления выходом, определяющий, какие из обратных вызовов вывода клиентов будут получать выходные данные. Возможные значения см. в разделе DEBUG_OUTCTL_XXX. Дополнительные сведения о выходных данных см. в разделе Входные и выходные данные.

[in] Mask

Указывает битовое поле выходного типа. Возможные значения см. в разделе DEBUG_OUTPUT_XXX .

[in] Format

Задает строку формата, как в printf. Как правило, символы преобразования работают точно так же, как и в C. Для символов преобразования с плавающей запятой 64-разрядный аргумент интерпретируется как 32-разрядное число с плавающей запятой, если не используется модификатор l .

Символ преобразования %p поддерживается, но он представляет указатель в адресном пространстве целевого объекта. Он может не иметь модификаторов и использует внутреннее форматирование отладчика. Поддерживаются следующие дополнительные символы преобразования.

Знак	Тип аргумента	Аргумент	Печатный текст
%p	ULONG64	Указатель в адресном пространстве.	Значение указателя.
%N	DWORD_PTR (32 или 64 бита в зависимости от архитектуры узла)	Указатель в виртуальном адресном пространстве узла.	Значение указателя. (Это эквивалентно стандартному символу C %p .)
%I	ULONG64	Любое 64-разрядное значение.	Указанное значение. Если значение больше 0xFFFFFFFF, оно выводится в виде 64-разрядного значения; В противном случае он выводится в виде 32-разрядного значения.
%ma	ULONG64	Адрес строки ASCII, завершаемой null, в виртуальном адресном пространстве процесса.	Указанная строка.
%mu	ULONG64	Адрес строки Юникода, завершаемой значением NULL, в виртуальном адресном пространстве процесса.	Указанная строка.
%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	Отладчик отформатированный указатель	Добавляет либо пустую строку, либо 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]

...

Указывает дополнительные параметры, представляющие значения, которые будут вставлены в выходные данные во время форматирования.

Возвращаемое значение

Этот метод также может возвращать значения ошибок. Дополнительные сведения см. в разделе Возвращаемые значения .

Код возврата	Описание
S_OK	Метод выполнен успешно.

При создании очень больших выходных строк можно достичь пределов подсистемы отладчика или операционной системы. Например, некоторые версии обработчика отладчика имеют ограничение в 16 КБ символов для одного вывода. Если вы обнаружите, что очень большие выходные данные усекаются, может потребоваться разделить выходные данные на несколько запросов.