HidP_GetSpecificButtonCaps function (hidpi.h)

Article
02/22/2024

The HidP_GetSpecificButtonCaps routine returns a button capability array that describes all HID control buttons in a top-level collection that meet a specified selection criteria.

Syntax

NTSTATUS HidP_GetSpecificButtonCaps(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USAGE                UsagePage,
  [in]      USHORT               LinkCollection,
  [in]      USAGE                Usage,
  [out]     PHIDP_BUTTON_CAPS    ButtonCaps,
  [in, out] PUSHORT              ButtonCapsLength,
  [in]      PHIDP_PREPARSED_DATA PreparsedData
);

Parameters

[in] ReportType

Specifies a HIDP_REPORT_TYPE enumerator value that identifies the report type.

[in] UsagePage

Specifies a usage page as a search criteria. If UsagePage is nonzero, only buttons that specify this usage page are returned.

[in] LinkCollection

Specifies a link collection as a search criteria. If LinkCollection is nonzero, only buttons that are part of this link collection are returned.

[in] Usage

Specifies a HID usage as a search criteria. If Usage is nonzero, only buttons that specify this usage will be returned.

[out] ButtonCaps

Pointer to a caller-allocated buffer in which the routine returns a button capability array for the specified report type.

[in, out] ButtonCapsLength

Specifies the length on input, in array elements, of the buffer provided at ButtonCaps. On output, this parameter is set to the number of elements that the routine actually returned.

[in] PreparsedData

Pointer to a top-level collection's preparsed data.

Return value

HidP_GetSpecificButtonCaps returns one of the following status values:

Return code	Description
HIDP_STATUS_SUCCESS	The routine successfully returned the capability data.
HIDP_STATUS_INVALID_PREPARSED_DATA	The preparsed data is not valid.

Remarks

The required size of the ButtonCaps array is specified by the NumberXxxButtonCaps members of a top-level collection's HIDP_CAPS structure.

When calling HidP_GetSpecificButtonCaps, specifying zero for UsagePage, Usage, and LinkCollection is equivalent to calling HidP_GetButtonCaps.

For more information about a collection's capability, see Obtaining Collection Information.

Requirements

Requirement	Value
Minimum supported client	Available in Windows 2000 and later versions of Windows.
Target Platform	Universal
Header	hidpi.h (include Hidpi.h)
Library	Hidparse.lib
IRQL	PASSIVE_LEVEL