HidP_GetUsagesEx function (hidpi.h)
The HidP_GetUsagesEx routine returns a list of the all the HID control button usages that are set to ON in a HID report.
Syntax
NTSTATUS HidP_GetUsagesEx(
[in] HIDP_REPORT_TYPE ReportType,
[in] USHORT LinkCollection,
[in, out] PUSAGE_AND_PAGE ButtonList,
[in, out] ULONG *UsageLength,
[in] PHIDP_PREPARSED_DATA PreparsedData,
[in] PCHAR Report,
[in] ULONG ReportLength
);
Parameters
[in] ReportType
Specifies a HIDP_REPORT_TYPE enumerator value that identifies the report type.
[in] LinkCollection
Specifies the link collection of the button usages. If LinkCollection is nonzero, the routine only returns information about the buttons that this link collection contains; otherwise, if LinkCollection is zero, the routine returns information about all the buttons in the top-level collection associated with PreparsedData.
[in, out] ButtonList
Pointer to a caller-allocated buffer that routine uses to return the usage and usage page identifiers for each button that is set to ON (1).
[in, out] UsageLength
Specifies, on input, the length, in array elements, of the ButtonList buffer. Specifies, on output, the number usages that are currently set to ON in the specified report.
[in] PreparsedData
Pointer to a top-level collection's preparsed data.
[in] Report
Pointer to a report that contains button data.
[in] ReportLength
Specifies the length, in bytes, of the report located at Report.
Return value
HidP_GetUsagesEx returns one of the following status values:
| Return code | Description |
|---|---|
|
The routine successfully returned all button usages set to ON. |
|
The report length is not valid. |
|
The specified report type is not valid. |
|
The UsageList buffer is too small to hold all the usages currently set to ON in the specified report. |
|
The collection contains buttons in a report of the specified type, but there are no such usages in the specified report. |
|
The preparsed data is not valid. |
Remarks
User-mode applications and kernel-mode drivers call HidP_MaxUsageListLength to determine the maximum number of buttons that be returned for specified report type. Alternatively, applications or drivers can call HidP_GetUsagesEx and set (*UsageLength) to zero to return the required length in UsageLength. In other words, UsageLength should be a valid pointer that points to a ULONG value 0 to get the required length.
Applications or drivers determine the required report length from the XxxReportByteLength members in a top-level collection's HIDP_CAPS structure.
For more information, see HID Collections.
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 | <= DISPATCH_LEVEL |