функция HidD_GetIndexedString (hidsdi.h)

Статья
02/07/2025

Подпрограмма HidD_GetIndexedString возвращает указанную внедренную строку из коллекции верхнего уровня.

Синтаксис

BOOLEAN HidD_GetIndexedString(
  [in]  HANDLE HidDeviceObject,
  [in]  ULONG  StringIndex,
  [out] PVOID  Buffer,
  [in]  ULONG  BufferLength
);

Параметры

[in] HidDeviceObject

Указывает открытый дескриптор коллекции верхнего уровня.

[in] StringIndex

Указывает индекс встроенной строки для конкретного устройства.

[out] Buffer

Указатель на выделенный вызывающим буфером, который подпрограмма использует для возврата внедренной строки, указанной StringIndex. Подпрограмма возвращает строку, завершаемую значением NULL, в формате, доступном для чтения.

[in] BufferLength

Указывает длину буфера, выделенного вызывающим объектом, в буфере. Если буфер недостаточно велик, чтобы вернуть всю встроенную строку, завершаемую null, подпрограмма возвращает ничего в буфере. Предоставленный буфер должен быть <= 4093 байта (2^12 – 3).

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

HidD_GetIndexedString возвращает TRUE, если он успешно возвращает всю встроенную строку, завершаемую значением NULL. В противном случае подпрограмма возвращает FALSE. Используйте GetLastError для получения расширенных сведений об ошибке.

Замечания

Только приложения в пользовательском режиме могут вызывать HidD_GetIndexedString. Драйверы в режиме ядра могут использовать запрос IOCTL_HID_GET_INDEXED_STRING.

Максимально возможное количество символов в внедренной строке — это конкретное устройство. Для USB-устройств максимальная длина строки составляет 126 широких символов (не включая завершающий символ NULL).

Элемент iProduct структуры USB_DEVICE_DESCRIPTOR для определенного интерфейса устанавливается универсальным родительским драйвером USB общего класса в соответствии со следующими правилами:

Если элемент iInterface структуры USB_INTERFACE_DESCRIPTOR для интерфейса является ненулевой, элемент iProduct структуры USB_DEVICE_DESCRIPTOR для интерфейса имеет элемент iInterface структуры USB_INTERFACE_DESCRIPTOR.
Если интерфейс сгруппирован дескриптором связи USB иiFunction элементом дескриптора ассоциации интерфейса для интерфейса ненулево, элемент iProduct структуры USB_DEVICE_DESCRIPTOR для интерфейса устанавливается iFunction член дескриптора ассоциации интерфейса.

Если предоставленный буфер не <= 4093 байт (2^12 – 3) вызов может завершиться сбоем (в зависимости от базового протокола, HID/Bluetooth/SPI) с кодом ошибки ERROR_GEN_FAILURE (0x0000001f)

Дополнительные сведения см. в коллекциях HID.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Windows 2000 и более поздних версиях Windows.
целевая платформа	Всеобщий
заголовка	hidsdi.h (include Hidsdi.h)
библиотеки	Hid.lib
DLL	Hid.dll