Функция vDbgPrintExWithPrefix (wdm.h)

Статья
08/08/2023

Подпрограмма vDbgPrintExWithPrefix отправляет строку отладчику ядра при соблюдении определенных условий. Эта подпрограмма может добавлять префикс к выходным данным отладчика для упорядочения результатов отладки.

Синтаксис

NTSYSAPI ULONG vDbgPrintExWithPrefix(
  [in] PCCH    Prefix,
  [in] ULONG   ComponentId,
  [in] ULONG   Level,
  [in] PCCH    Format,
  [in] va_list arglist
);

Параметры

[in] Prefix

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

Например, подпрограмма конкретного компонента может указывать имя компонента при вызове vDbgPrintExWithPrefix. Эта подпрограмма автоматически добавляет имя компонента в начало всех выходных данных отладки, которые передаются в отладочную процедуру печати компонента.

[in] ComponentId

Компонент, вызывающий эту подпрограмму. Этот параметр должен быть одним из идентификаторов фильтров имен компонентов, определенных в Dpfilter.h. Чтобы избежать смешивания выходных данных драйвера с выходными данными компонентов Windows, следует использовать только следующие значения для ComponentId:

DPFLTR_IHVVIDEO_ID
DPFLTR_IHVAUDIO_ID
DPFLTR_IHVNETWORK_ID
DPFLTR_IHVSTREAMING_ID
DPFLTR_IHVBUS_ID
DPFLTR_IHVDRIVER_ID

[in] Level

Серьезность отправляемого сообщения. Этот параметр может быть любым 32-разрядным целым числом. Значения от 0 до 31 (включительно) обрабатываются иначе, чем значения от 32 до 0xFFFFFFFF. Дополнительные сведения о том, как обрабатываются значения, см. в разделе Чтение и фильтрация сообщений отладки.

[in] Format

Указатель на строку формата для печати. Строка format поддерживает большинство кодов форматирования в стиле printf. Однако коды формата Юникода (%C, %S, %lc, %ls, %wc, %ws и %wZ) можно использовать только с IRQL = PASSIVE_LEVEL. Подпрограмма vDbgPrintExWithPrefix не поддерживает типы с плавающей запятой (%f, %e, %E, %g, %G, %a или %A).

[in] arglist

Список аргументов для строки формата. Подпрограмма vDbgPrintExWithPrefix использует этот список так же, как vprintf .

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

vDbgPrintExWithPrefix возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае эта подпрограмма возвращает соответствующий код ошибки.

VDbgPrintExWithPrefix можно вызвать по адресу IRQL <= DIRQL. Однако коды формата Юникода (%wc и %ws) можно использовать только в IRQL = PASSIVE_LEVEL. Кроме того, так как отладчик использует межпроцессные прерывания (IPIs) для взаимодействия с другими процессорами, вызов vDbgPrintExWithPrefix в IRQL > DIRQL может привести к взаимоблокировкам.

vDbgPrintExWithPrefix либо передает созданную строку отладчику ядра, либо ничего не делает в зависимости от значений ComponentId, Level и соответствующих масок фильтра компонентов. Дополнительные сведения о том, что делает vDbgPrintEx , см. в разделе Чтение и фильтрация сообщений отладки.

Если это не является абсолютно необходимым, не следует получать строку из входных данных пользователя или другого процесса и передавать ее в vDbgPrintExWithPrefix. Если используется строка, которую вы не создали, необходимо убедиться, что эта строка является допустимой строкой формата и что коды формата соответствуют списку аргументов по типу и количеству. Рекомендуется, чтобы все строки форматирования были статическими и определенными во время компиляции.

Не существует верхнего предела для размера строки format или количества аргументов в списке arglist . Однако любой один вызов vDbgPrintExWithPrefix передает только 512 байт информации.

Существует также ограничение на размер буфера, используемого отладчиком. Дополнительные сведения об этом ограничении см. в разделе Буфер DbgPrint и отладчик.

Эта подпрограмма определена в Wdm.h. Идентификаторы фильтров компонентов определяются в Dpfilter.h.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Microsoft Windows XP и более поздних версиях операционной системы.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Dpfilter.h, Wdm.h, Ntddk.h, Ndis.h)
Библиотека	NtDll.lib (пользовательский режим); NtosKrnl.lib (режим ядра)
DLL	NtDll.dll (пользовательский режим); NtosKrnl.exe (режим ядра)
IRQL	<= DIRQL (см. раздел Комментарии)

См. также раздел

DbgPrintEx

vDbgPrintEx

Поделиться через