IOCTL_HID_GET_STRING IOCTL (hidport.h)

Статья
08/07/2023

Запрос IOCTL_HID_GET_STRING получает идентификатор производителя, код продукта или серийный номер для коллекции верхнего уровня. Полученная строка — это строка с широкими символами, заканчивающаяся NULL, в понятном для человека формате.

Общие сведения об устройствах HIDClass см. в разделе Коллекции HID.

Основной код

IRP_MJ_DEVICE_CONTROL

Входной буфер

IOCTL_HID_GET_STRING использует два входных буфера.

Parameters.DeviceIoControl.OutputBufferLength в расположении стека ввода-вывода IRP указывает размер в байтах заблокированного выходного буфера в Irp-UserBuffer>. Если выходной буфер недостаточно велик для хранения всей строки, завершаемой null, запрос не возвращает ничего в выходном буфере. Максимально возможное количество символов во внедренной строке зависит от устройства. Для USB-устройств максимальная длина строки составляет 126 символов в ширину (без учета завершающего символа NULL).

Parameters.DeviceIoControl.Type3InputBuffer в расположении стека ввода-вывода IRP содержит составное значение. Два наиболее важных байта содержат идентификатор языка извлекаемой строки. Два наименее значимых байта содержат одно из следующих трех значений констант:

HID_STRING_ID_IMANUFACTURER
HID_STRING_ID_IPRODUCT
HID_STRING_ID_ISERIALNUMBER

Мини-накопитель HID определяет, какая из этих трех констант присутствует в двух нижних байтах входного буфера, после чего он должен получить соответствующий строковый индекс из дескриптора устройства. Сведения о дескрипторове устройства хранятся в расширении устройства коллекции верхнего уровня, связанной с устройством.

Важно не путать эти три константы с фактическими строковыми индексами идентификаторов. Эти константы представляют смещения в дескрипторе устройства, где можно найти соответствующие строковые индексы.

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

Длина входного буфера

Размер объекта OutputBufferLength и размер Type3InputBuffer.

Выходной буфер

Мини-диск HID заполняет буфер в Irp-UserBuffer> запрошенной строкой (широкой символьной строкой с завершением NULL).

Длина выходного буфера

Размер UserBuffer.

Блок состояния

Мини-накопители HID, выполняющие операции ввода-вывода на устройство, задают следующие поля Irp-IoStatus>:

Для сведений задается количество байтов, передаваемых с устройства.
Состояние устанавливается в STATUS_SUCCESS, если передача выполнена без ошибок. В противном случае устанавливается соответствующий код ошибки NTSTATUS.

Мини-накопители HID, которые вызывают другие драйверы с этим IOCTL для выполнения операций ввода-вывода на устройство, должны убедиться, что поле Information блока состояния правильно и не изменяет содержимое поля Состояние .