HidP_SetUsageValueArray
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
This function sets a HID control usage value array in a specified HID report.
Syntax
NTSTATUS HidP_SetUsageValueArray(
HIDP_REPORT_TYPE ReportType,
USAGE UsagePage,
USHORT LinkCollection,
USAGE Usage,
PCHAR UsageValue,
USHORT UsageValueByteLength,
PHIDP_PREPARSED_DATA PreparsedData,
PCHAR Report,
ULONG ReportLength
);
Parameters
- ReportType
[in] HIDP_REPORT_TYPE enumerator value that indicates the type of HID report located at Report.
- UsagePage
[in] Usage page of a usage.
- LinkCollection
[in] Optional. Link collection that contains the usage. If LinkCollection is nonzero, the function only sets the usage, if one exists, in this link collection. If LinkCollection is zero, the function sets the first usage it finds in the top-level collection associated with PreparsedData.
- Usage
[in] Usage.
- UsageValue
[in] Pointer to a caller-allocated buffer that contains the data associated with the usage value array.
- UsageValueByteLength
[in] Length, in bytes, of the UsageValue buffer.
- PreparsedData
[in] Pointer to a top-level's preparsed data.
- Report
[out] Pointer to a HID report.
- ReportLength
[in] Size, in bytes, of the HID report located at Report, which must be equal to the report length for the specified report type that HidP_GetCaps returns in a collection's HIDP_CAPS structure.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
HIDP_STATUS_SUCCESS |
The function has successfully set the usage value. |
HIDP_STATUS_INVALID_REPORT_LENGTH |
Report length is not valid. |
HIDP_STATUS_INVALID_REPORT_TYPE |
Specified report type is not valid. |
HIDP_STATUS_BUFFER_TOO_SMALL |
Size, in bytes, of the UsageValue buffer is too small. |
HIDP_STATUS_INCOMPATIBLE_REPORT_ID |
Report contains a collection with buttons in the specified usage page, but there are no such usages in the report. |
HIDP_STATUS_NOT_VALUE_ARRAY |
Specified usage is not a usage value array. |
HIDP_STATUS_INVALID_PREPARSED_DATA |
Preparsed data is not valid. |
HIDP_STATUS_REPORT_DOES_NOT_EXIST |
No reports of the specified type exist. |
HIDP_STATUS_NOT_IMPLEMENTED |
Report size of data fields specified for the usage value array is not a multiple of eight bits. |
HIDP_STATUS_USAGE_NOT_FOUND |
Report contains a requested usage that is not in any report supported by the top-level collection. |
Remarks
The terms button and usage are used synonymously.
Multiplying the BitSize and ReportCount members of the usage value array's HIDP_VALUE_CAPS structure, and rounding the result up to the nearest byte, determines the required size of the UsageValue buffer.
HidP_SetUsageValueArray only supports usage value arrays where each data field of the array is a multiple of eight bits.
The caller must set the UsageValue buffer exactly as it should occur in the report.
Requirements
| Header | hidpi.h |
| Library | Hidparse_lib.lib |
| Windows Embedded CE | Windows CE .NET 4.2 and later |
See Also
Reference
HIDP_CAPS
HidP_GetCaps
HIDP_REPORT_TYPE
HidP_SetScaledUsageValue
HidP_SetUsageValue
HIDP_VALUE_CAPS