Интерпретация отчетов HID
В этой статье описывается, как приложения в пользовательском режиме и драйверы в режиме ядра используют подпрограммы поддержки HIDClass HidP_Xxxдля интерпретации данных управления в отчете HID.
Извлечение данных значений путем указания его использования
Чтобы извлечь данные значений из отчета HID, приложение или драйвер может использовать одну из следующих подпрограмм поддержки HID:
- HidP_GetScaledUsageValue Возвращает подписанное и масштабируемое значение.
- HidP_GetUsageValue Возвращает немасштабированное значение в формате без знака или масштабируемое значение, которое выходит за пределы его обычного диапазона.
- HidP_GetUsageValueArray Возвращает массив значений использования.
Чтобы использовать HidP_GetUsageValueArray приложения и драйверы, необходимо выделить буфер с нулевой инициализацией, который достаточно велик для хранения массива значений использования. Требуемый размер в байтах — это продукт элементов BitSize и ReportCount HIDP_VALUE_CAPS структуры массива значений использования, округленный до ближайшего байта.
Извлечение использования кнопки, для которых задано значение ON
Чтобы извлечь использование HID кнопок, которые имеют значение ON (1), приложения и драйверы вызывают одну из следующих подпрограмм поддержки HID:
- HidP_GetButtons (или HidP_GetUsages) Возвращает идентификатор использования всех кнопок на указанной странице использования, для которых задано значение ON.
- HidP_GetButtonsEx (или HidP_GetUsagesEx) Возвращает страницу использования и идентификатор использования всех кнопок, для которых задано значение ON.
Эти подпрограммы возвращают массив всех сведений об использовании для всех кнопок, которые в настоящее время имеют значение ON. Неявно кнопки, использование которых не возвращается этими подпрограммами, равное OFF (ноль).
Чтобы вызвать эти подпрограммы, приложения и драйверы должны сначала выделить и инициализировать буфер, используемый для возврата массива использования кнопки. Приложение или драйвер вызывает HidP_MaxUsageListLength , чтобы определить количество использования кнопки на указанной странице использования в отчете. Если приложение или драйвер указывает страницу использования нуля, подпрограмма возвращает количество всех использования кнопки в отчете.
Обязательный размер буфера в байтах:
- (для HidP_GetButtons) Значение, возвращаемое HidP_MaxUsageListLength раз sizeof(USAGE)
- (для HidP_GetButtonsEx) Значение, возвращаемое HidP_MaxUsageListLength раз sizeof(USAGE_AND_PAGE)
После того как приложение или драйвер использует эти подпрограммы для получения сведений о том, какие кнопки в настоящее время заданы в on, он может определить разницу между текущим состоянием и предыдущим состоянием кнопок, вызвав одну из следующих подпрограмм поддержки HIDClass. Эти подпрограммы возвращают разницу между двумя массивами сведений об использовании:
Извлечение и настройка данных управления по индексам данных
Чтобы использовать индексы данных для извлечения и задания данных управления в отчете HID, приложение или драйвер может использовать следующие подпрограммы поддержки HIDClass:
Эти подпрограммы полезны для приложения или драйвера, предоставляющего службу "добавленной стоимости". Например, один из них предоставляет пользовательский интерфейс для всех элементов управления, поддерживаемых устройством HIDClass. Microsoft DirectInput является одним из примеров.
Приложение или драйвер, вызывающий эти подпрограммы, может наиболее эффективно получать и задавать все значения в отчете. Например, чтобы получить все данные о значении по их использованию HID, он должен вызывать HidP_GetUsageValue для каждого использования. Однако для получения всех данных значения по индексу данных необходимо вызывать только HidP_GetData один раз.
Приложение или драйвер используют индексы данных, указанные в массивах возможностей кнопки коллекции и массивах возможностей значений для идентификации использования HID.
Задание данных значения путем указания его использования
Приложение или драйвер может задать значение в правильно инициализированном отчете HID, вызвав одну из следующих подпрограмм поддержки HID:
- HidP_SetScaledUsageValue Задает подписанное и масштабируемое значение в отчете.
- HidP_SetUsageValue Задает значение в отчете.
- HidP_SetUsageValueArray Задает массив значений использования в отчете.
Задание состояния кнопки путем указания его использования
Приложение или драйвер может задать состояние кнопок в правильно инициализированном отчете HID, вызвав одну из следующих подпрограмм поддержки HIDClass:
- HidP_SetButtons (или HidP_SetUsages) Задает указанный набор кнопок в on (1).
- HidP_UnsetButtons (или HidP_UnsetUsages) задает указанный набор кнопок в значение OFF (ноль).
Извлечение и настройка данных управления HID по индексам данных
Чтобы использовать индексы данных для извлечения и задания данных управления в отчете HID, приложение или драйвер может использовать следующие подпрограммы поддержки HIDClass:
Эти подпрограммы полезны для приложения или драйвера, предоставляющего службу "добавленной стоимости". Например, один из них предоставляет пользовательский интерфейс для всех элементов управления, поддерживаемых устройством HIDClass. Microsoft DirectInput является одним из примеров.
Приложение или драйвер, вызывающий эти подпрограммы, может наиболее эффективно получать и задавать все значения в отчете. Например, чтобы получить все данные о значении по их использованию HID, он должен вызывать HidP_GetUsageValue для каждого использования. Однако для получения всех данных значения по индексу данных необходимо вызывать только HidP_GetData один раз.
Приложение или драйвер используют индексы данных, указанные в массивах возможностей кнопки коллекции и массивах возможностей значений для идентификации использования HID.