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

функция HidP_GetButtonArray (hidpi.h)

  • Статья

HidP_GetButtonArray возвращает массив структур HIDP_BUTTON_ARRAY_DATA для указанного отчета.

Синтаксис

NTSTATUS HidP_GetButtonArray(
  HIDP_REPORT_TYPE        ReportType,
  USAGE                   UsagePage,
  USHORT                  LinkCollection,
  USAGE                   Usage,
  PHIDP_BUTTON_ARRAY_DATA ButtonData,
  PUSHORT                 ButtonDataLength,
  PHIDP_PREPARSED_DATA    PreparsedData,
  PCHAR                   Report,
  ULONG                   ReportLength
);

Параметры

ReportType

Значение из перечисления HIDP_REPORT_TYPE.

UsagePage

Страница использования, на которую ссылается данное использование.

LinkCollection

(Необязательно) Это значение можно использовать для разделения двух полей, которые могут иметь одинаковые UsagePage и Использование, но существуют в разных коллекциях. Если значение LinkCollection HIDP_LINK_COLLECTION_UNSPECIFIED, будет возвращен первый массив кнопки, соответствующий UsagePage и Usage, независимо от расположения. Если значение LinkCollection HIDP_LINK_COLLECTION_ROOT, будет возвращен первый массив кнопки, соответствующий UsagePage и Usage.

Usage

Использование, кнопки которого HidP_GetButtonArray будут извлекаться.

ButtonData

Массив структур HIDP_BUTTON_ARRAY_DATA, где будут размещены данные кнопок, заданных для ON. Необходимое количество элементов — это поле ReportCountHIDP_BUTTON_CAPS для этого элемента управления. Этот буфер предоставляется вызывающим объектом.

ButtonDataLength

В качестве входных данных этот параметр указывает длину параметра ButtonData в количестве элементов массива, а не число байтов. В качестве выходных данных, если возвращается HIDP_STATUS_SUCCESS, это значение указывает, сколько из этих элементов массива заполнено функцией. Максимальное количество возвращаемых HIDP_BUTTON_ARRAY_DATA структур определяется HIDP_BUTTON_CAPS. ReportCount. Если возвращается HIDP_STATUS_BUFFER_TOO_SMALL, это значение содержит количество элементов массива, необходимых для успешного выполнения запроса.

PreparsedData

Предварительно проанализированные данные, возвращаемые HIDCLASS.

Report

Пакет отчета. Первый байт должен быть ReportId. Это будет правильно установлено, если отчет считывается из системы.

ReportLength

Длина заданного пакета отчета в байтах.

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

HidP_GetButtonArray возвращает одно из следующих значений состояния:

Возвращаемый код Описание
HIDP_STATUS_SUCCESS Успешно извлечены кнопки из пакета отчета
HIDP_STATUS_INVALID_REPORT_TYPE Недопустимый параметр ReportType
HIDP_STATUS_INVALID_PREPARSED_DATA Недопустимый параметр PreparsedData
HIDP_STATUS_INVALID_REPORT_LENGTH Длина пакета отчета не равна длине, указанной в структуре HIDP_CAPS для заданного типа отчета ReportType
HIDP_STATUS_NOT_BUTTON_ARRAY Указанный элемент управления не является массивом кнопок
HIDP_STATUS_BUFFER_TOO_SMALL Размер переданного в буфере, в котором возврат массива слишком мал
HIDP_STATUS_INCOMPATIBLE_REPORT_ID Указанная страница использования, коллекция ссылок и использования существует в отчете с другим идентификатором отчета, отличным от передаваемого отчета.
HIDP_STATUS_USAGE_NOT_FOUND Страница использования, использование и сочетание коллекции ссылок не существует в отчетах для этого ReportType

Замечания

Вызывающий объект должен использовать HidP_GetVersion, чтобы определить, доступна ли эта функция. HidP_GetButtonArray доступен только в том случае, если HidP_GetVersion возвращает значение двух или более поздней версии. Версия 2 API соответствует Windows 11.

Массив кнопок возникает, когда последнее использование в последовательности использования, описывающего основной элемент, должно повторяться, так как для данного основного элемента определено меньше использования, чем ReportCount объявлены для данного основного элемента. В этом случае для использования выделяется один HIDP_BUTTON_CAPS, а для ReportCountHIDP_BUTTON_CAPS задано количество полей, к которым относится использование.

HIDP_BUTTON_CAPS, описывающий массив кнопок, всегда будет иметь ReportCount больше одного. Если ReportCount равно одному, то он не является массивом кнопок и не может использоваться с HidP_GetButtonArray. Вместо этого см. HidP_GetUsages.

Требования

Требование Ценность
заголовка hidpi.h

См. также