HidP_GetUsages
This function returns a list of the HID control button usages that are in a specified usage page and are set to ON in a HID report.
NTSTATUS HidP_GetUsages(
HIDP_REPORT_TYPE ReportType,
USAGE UsagePage,
USHORT LinkCollection,
USAGE* UsageList,
ULONG* UsageLength,
PHIDP_PREPARSED_DATA PreparsedData,
PCHAR Report,
ULONG ReportLength
);
Parameters
- ReportType
[in] HIDP_REPORT_TYPE enumerator value that identifies the report type. - UsagePage
[in] Usage page of the button usages. The function only returns information about buttons in this usage page - LinkCollection
[in] Optional. Link collection of the button usages. If LinkCollection is nonzero, the function only returns information about the buttons that this link collection contains; otherwise, if LinkCollection is zero, the function returns information about all the buttons in the top-level collection associated with PreparsedData. - UsageList
[out] Pointer to a caller-allocated buffer that the function uses to return the usages of all buttons that are set to ON and belong to the usage page specified by UsagePage. - UsageLength
[in, out] On input, the length in array elements of the UsageList buffer. On output, the number of buttons set to ON in the specified usage page. - PreparsedData
[in] Pointer to a top-level collection's preparsed data. - Report
[in] Pointer to a report. - ReportLength
[in] Length, in bytes, of the report located at Report.
Return Values
The following table shows the possible return values for this function.
Value | Description |
---|---|
HIDP_STATUS_SUCCESS | The function successfully returned all button usages set to ON. |
HIDP_INVALID_REPORT_LENGTH | Report length was not valid. |
HIDP_INVALID_REPORT_TYPE | Specified report type was not valid. |
HIDP_STATUS_BUFFER_TOO_SMALL | In the specified usage page, UsageList buffer was too small to hold all the usages that are currently set to ON. |
HIDP_STATUS_INCOMPATIBLE_REPORT_ID | Report contained a collection with buttons in the specified usage page, but there were no such usages in the report. |
HIDP_STATUS_INVALID_PREPARSED_DATA | Preparsed data was not valid. |
HIDP_STATUS_USAGE_NOT_FOUND | Report contained a requested usage that was not in any report supported by the top-level collection. |
Remarks
The terms button and usage are used synonymously.
User-mode applications and kernel-mode drivers call HidP_MaxUsageListLength to determine the maximum number of buttons that this function can return for a specified report type. Alternatively, applications or drivers can call HidP_GetButtons and set UsageList to zero to return the required length in UsageLength.
Applications or drivers determine the required report length from the XXXReportByteLength members in a top-level collection's HIDP_CAPS structure.
Requirements
OS Versions: Windows CE .NET 4.2 and later.
Header: Hidpi.h.
Link Library: Hidparse_lib.lib.
See Also
HID Drivers | HIDP_CAPS | HidP_GetButtons | HidP_GetButtonsEx | HidP_GetCaps | HidP_GetScaledUsageValue | HidP_GetUsagesEx | HidP_GetUsageValue | HidP_GetUsageValueArray | HidP_MaxUsageListLength | HIDP_REPORT_TYPE
Last updated on Tuesday, May 18, 2004
© 1992-2003 Microsoft Corporation. All rights reserved.