Edit

Share via

HidP_SetButtonArray function (hidpi.h)

  • Article

The HidP_SetButtonArray function sets the state of buttons via an array of HIDP_BUTTON_ARRAY_DATA structures.

Syntax

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

Parameters

ReportType

A value of either HidP_Output or HidP_Feature from the HIDP_REPORT_TYPE enum.

UsagePage

The usage page to which the given usage refers.

LinkCollection

(Optional) This value can be used to differentiate between two fields that may have the same UsagePage and Usage but exist in different collections. If the value is HIDP_LINK_COLLECTION_UNSPECIFIED, the first found button array matching the UsagePage and Usage will be returned, regardless of location. If the value is HIDP_LINK_COLLECTION_ROOT, the first found button array, in the root collection, matching the UsagePage and Usage will be returned.

Usage

The usage whose button array HidP_SetButtonArray will set.

ButtonData

The buffer with the values to set into the button array.

ButtonDataLength

Number of elements in the ButtonData buffer.

PreparsedData

The parsed data returned from HIDCLASS.

Report

The report packet. The first byte must be the ReportId.

ReportLength

Length of the given report packet in bytes.

Return value

HidP_SetButtonArray returns one of the following status values:

Return code Description
HIDP_STATUS_SUCCESS The button array in the report packet was set successfully
HIDP_STATUS_INVALID_REPORT_TYPE ReportType is not valid
HIDP_STATUS_INVALID_PREPARSED_DATA PreparsedData is not valid
HIDP_STATUS_INVALID_REPORT_LENGTH The length of the report packet is not equal to the length specified in the HIDP_CAPS structure for the given ReportType
HIDP_STATUS_REPORT_DOES_NOT_EXIST There are no reports on this device for the given ReportType
HIDP_STATUS_NOT_BUTTON_ARRAY The control specified is not a button array
HIDP_STATUS_INCOMPATIBLE_REPORT_ID The specified usage page, usage, and link collection exists in a report with a different report ID than the report being passed in
HIDP_STATUS_USAGE_NOT_FOUND The usage page, usage, and link collection combination does not exist in any reports for this ReportType
HIDP_STATUS_DATA_INDEX_OUT_OF_RANGE The ArrayIndex for one of the supplied HIDP_BUTTON_ARRAY_DATA structures is outside the valid range for this button array

Remarks

HidP_SetButtonArray sets the state of buttons for the first button array found, within the specified LinkCollection, with the supplied Usage for the specified Report.

The caller should use HidP_GetVersion to determine if this function is available. HidP_SetButtonArray is only available if HidP_GetVersion returns a value of two or greater. Version two of the API corresponds to Windows 11.

A button array occurs when the last usage in the sequence of usages describing a main item, must be repeated because there are less usages defined than the ReportCount declared for the given main item. In this case, a single HIDP_BUTTON_CAPS is allocated for that usage and the ReportCount of the HIDP_BUTTON_CAPS is set to reflect the number of fields the usage refers.

A HIDP_BUTTON_CAPS that describes a button array, will always have ReportCount greater than one. If ReportCount equals one, then it is not a button array and cannot be used with HidP_SetButtonArray. For more information, see HidP_SetUsages.

Requirements

Requirement Value
Header hidpi.h

See also