Метод IDebugControl::ControlledOutputVaList (dbgeng.h)
Метод 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, если выходной формат (первый аргумент) — 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}: "Hello <World>"
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.
Возвращаемое значение
| Код возврата | Описание |
|---|---|
|
Метод выполнен успешно. |
Этот метод также может возвращать значения ошибок. Дополнительные сведения см. в разделе Возвращаемые значения .
Комментарии
При создании очень больших выходных строк можно достичь пределов подсистемы отладчика или операционной системы. Например, некоторые версии обработчика отладчика имеют ограничение в 16 КБ символов для одного вывода. Если вы обнаружите, что очень большие выходные данные усекаются, может потребоваться разделить выходные данные на несколько запросов.
Макросы va_list, va_start и va_end определяются в Stdarg.h.
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Персональный компьютер |
| Верхняя часть | dbgeng.h (включая Dbgeng.h, Stdarg.h) |