HidP_GetButtonArray función (hidpi.h)
HidP_GetButtonArray devuelve una matriz de estructuras de HIDP_BUTTON_ARRAY_DATA para el informe especificado.
Sintaxis
NTSTATUS HidP_GetButtonArray(
HIDP_REPORT_TYPE ReportType,
USAGE UsagePage,
USHORT LinkCollection,
USAGE Usage,
PHIDP_BUTTON_ARRAY_DATA ButtonData,
PUSHORT ButtonDataLength,
PHIDP_PREPARSED_DATA PreparsedData,
PCHAR Report,
ULONG ReportLength
);
Parámetros
ReportType
Valor de la enumeración HIDP_REPORT_TYPE .
UsagePage
Página de uso a la que hace referencia el uso especificado.
LinkCollection
(Opcional) Este valor se puede usar para diferenciar entre dos campos que pueden tener el mismo UsagePage y Usage , pero que existen en colecciones diferentes. Si el valor linkCollection es HIDP_LINK_COLLECTION_UNSPECIFIED, se devolverá la primera matriz de botones que coincida con UsagePage y Usage , independientemente de la ubicación. Si el valor linkCollection es HIDP_LINK_COLLECTION_ROOT, se devolverá la primera matriz de botones que se encuentra en la colección raíz que coincida con UsagePage y Usage .
Usage
El uso cuyos botones HidP_GetButtonArray recuperará.
ButtonData
Matriz de estructuras de HIDP_BUTTON_ARRAY_DATA donde se colocarán los datos de los botones establecidos ON en . El número de elementos necesarios es el campo ReportCount del HIDP_BUTTON_CAPS para este control. El autor de la llamada proporciona este búfer.
ButtonDataLength
Como entrada, este parámetro especifica la longitud del parámetro ButtonData en el número de elementos de matriz, no el número de bytes. Como salida, si se devuelve HIDP_STATUS_SUCCESS, este valor se establece para indicar cuántos de esos elementos de matriz ha rellenado la función . El número máximo de estructuras de HIDP_BUTTON_ARRAY_DATA que se pueden devolver viene determinada por HIDP_BUTTON_CAPS. ReportCount. Si se devuelve HIDP_STATUS_BUFFER_TOO_SMALL, este valor contiene el número de elementos de matriz necesarios para completar correctamente la solicitud.
PreparsedData
Los datos analizados previamente devueltos por HIDCLASS.
Report
Paquete de informe. El primer byte debe ser reportId. Esto se establecerá correctamente si el informe se lee desde el sistema.
ReportLength
Longitud del paquete de informe especificado en bytes.
Valor devuelto
HidP_GetButtonArray devuelve uno de los siguientes valores de estado:
| Código devuelto | Descripción |
|---|---|
| HIDP_STATUS_SUCCESS | Se recuperaron correctamente los botones del paquete del informe. |
| HIDP_STATUS_INVALID_REPORT_TYPE | El parámetro ReportType no es válido |
| HIDP_STATUS_INVALID_PREPARSED_DATA | El parámetro PreparsedData no es válido |
| HIDP_STATUS_INVALID_REPORT_LENGTH | La longitud del paquete de informe no es igual a la longitud especificada en la estructura de HIDP_CAPS para el reportType especificado. |
| HIDP_STATUS_NOT_BUTTON_ARRAY | El control especificado no es una matriz de botones |
| HIDP_STATUS_BUFFER_TOO_SMALL | El tamaño del búfer pasado en el que devolver la matriz es demasiado pequeño. |
| HIDP_STATUS_INCOMPATIBLE_REPORT_ID | La página de uso, el uso y la colección de vínculos especificados existen en un informe con un identificador de informe diferente al que se pasa en el informe. |
| HIDP_STATUS_USAGE_NOT_FOUND | La combinación de la colección de vínculos, uso y página de uso no existe en ningún informe de este reportType. |
Comentarios
El autor de la llamada debe usar HidP_GetVersion para determinar si esta función está disponible. HidP_GetButtonArray solo está disponible si HidP_GetVersion devuelve un valor de dos o más. La versión dos de la API corresponde a Windows 11.
Una matriz de botones se produce cuando el último uso de la secuencia de usos que describe un elemento principal, debe repetirse porque hay menos usos definidos que el ReportCount declarado para el elemento principal especificado. En este caso, se asigna un único HIDP_BUTTON_CAPS para ese uso y el ReportCount del HIDP_BUTTON_CAPS se establece para reflejar el número de campos a los que hace referencia el uso.
Un HIDP_BUTTON_CAPS que describe una matriz de botones siempre tendrá ReportCount mayor que uno. Si ReportCount es igual a uno, no es una matriz de botones y no se puede usar con HidP_GetButtonArray. Vea HidP_GetUsages en su lugar.
Requisitos
| Requisito | Valor |
|---|---|
| Header | hidpi.h |