Share via

функция 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 и Usage , но существуют в разных коллекциях. Если значение 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 Сочетание страницы использования, использования и коллекции ссылок не существует ни в одном отчете для этого типа отчета.

Комментарии

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

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

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

Требования

Требование Значение
Заголовок hidpi.h

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