Метод IDebugControl::ControlledOutput (dbgeng.h)

Статья
08/07/2023

Метод 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. Для символов преобразования с плавающей запятой 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 КБ символов для одного вывода. Если вы обнаружите, что очень большие выходные данные усекаются, может потребоваться разделить выходные данные на несколько запросов.