Метод IDebugControl2::ControlledOutputVaList (dbgeng.h)

Статья
02/06/2025

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

Синтаксис

HRESULT ControlledOutputVaList(
  [in] ULONG   OutputControl,
  [in] ULONG   Mask,
  [in] PCSTR   Format,
  [in] va_list Args
);

Параметры

[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, если выходной формат (первый arg) — DML.
%Y{T}	Струна	СМС	Строка с кавычками. Всегда преобразует текст в DML независимо от формата выходных данных.
%Y{s}	Струна	СМС	Неквотированная строка. Преобразует текст в DML, если выходной формат (первый arg) — 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]

[in] Args

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

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

Возвращаемый код	Описание
S_OK	Метод был успешным.

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

Замечания

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

Макросы va_list, va_startи va_end определены в Stdarg.h.