função HidP_GetButtonArray (hidpi.h)
HidP_GetButtonArray retorna uma matriz de estruturas de HIDP_BUTTON_ARRAY_DATA para o relatório especificado.
Sintaxe
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
Um valor da enumeração HIDP_REPORT_TYPE.
UsagePage
A página de uso à qual o uso especificado se refere.
LinkCollection
(Opcional) Esse valor pode ser usado para diferenciar entre dois campos que podem ter o mesmo UsagePage e de Uso, mas existem em coleções diferentes. Se o valor do LinkCollection for HIDP_LINK_COLLECTION_UNSPECIFIED, a primeira matriz de botões encontrada que corresponde ao UsagePage e Use será retornada, independentemente do local. Se o valor LinkCollection for HIDP_LINK_COLLECTION_ROOT, a primeira matriz de botões encontrada na coleção raiz que corresponde ao UsagePage e Usage será retornada.
Usage
O uso cujos botões HidP_GetButtonArray serão recuperados.
ButtonData
Uma matriz de estruturas HIDP_BUTTON_ARRAY_DATA em que os dados de botões definidos como ON serão colocados. O número de elementos necessários é o campo ReportCount do HIDP_BUTTON_CAPS para esse controle. Esse buffer é fornecido pelo chamador.
ButtonDataLength
Como entrada, esse parâmetro especifica o comprimento do parâmetro ButtonData em número de elementos de matriz, não o número de bytes. Como saída, se HIDP_STATUS_SUCCESS for retornado, esse valor será definido para indicar quantos desses elementos de matriz foram preenchidos pela função. O número máximo de estruturas de HIDP_BUTTON_ARRAY_DATA que podem ser retornadas é determinado por HIDP_BUTTON_CAPS. ReportCount. Se HIDP_STATUS_BUFFER_TOO_SMALL for retornado, esse valor conterá o número de elementos de matriz necessários para concluir a solicitação com êxito.
PreparsedData
Os dados pré-analisados retornados pelo HIDCLASS.
Report
O pacote de relatório. O primeiro byte deve ser o ReportId. Isso será definido corretamente se o relatório for lido do sistema.
ReportLength
Comprimento do pacote de relatório especificado em bytes.
Valor de retorno
HidP_GetButtonArray retorna um dos seguintes valores de status:
| Código de retorno | Descrição |
|---|---|
| HIDP_STATUS_SUCCESS | Recuperou com êxito os botões do pacote de relatório |
| HIDP_STATUS_INVALID_REPORT_TYPE | O parâmetro ReportType não é válido |
| HIDP_STATUS_INVALID_PREPARSED_DATA | O parâmetro PreparsedData não é válido |
| HIDP_STATUS_INVALID_REPORT_LENGTH | O comprimento do pacote de relatório não é igual ao comprimento especificado na estrutura de HIDP_CAPS para o ReportType determinado |
| HIDP_STATUS_NOT_BUTTON_ARRAY | O controle especificado não é uma matriz de botões |
| HIDP_STATUS_BUFFER_TOO_SMALL | O tamanho do buffer passado no qual retornar a matriz é muito pequeno |
| HIDP_STATUS_INCOMPATIBLE_REPORT_ID | A página de uso, o uso e a coleção de links especificados existem em um relatório com uma ID de relatório diferente do relatório que está sendo passado |
| HIDP_STATUS_USAGE_NOT_FOUND | A página de uso, o uso e a combinação da coleção de links não existem em nenhum relatório para este reportType |
Observações
O chamador deve usar HidP_GetVersion para determinar se essa função está disponível. HidP_GetButtonArray só estará disponível se HidP_GetVersion retornar um valor de dois ou mais. A versão dois da API corresponde ao Windows 11.
Uma matriz de botões ocorre quando o último uso na sequência de usos que descreve um item principal deve ser repetido porque há menos usos definidos do que o ReportCount declarado para o item principal especificado. Nesse caso, um único HIDP_BUTTON_CAPS é alocado para esse uso e o ReportCount do HIDP_BUTTON_CAPS é definido para refletir o número de campos aos quais o uso se refere.
Um HIDP_BUTTON_CAPS que descreve uma matriz de botões sempre terá ReportCount maior que um. Se ReportCount for igual a uma, ela não será uma matriz de botões e não poderá ser usada com HidP_GetButtonArray. Veja HidP_GetUsages em vez disso.
Requisitos
| Requisito | Valor |
|---|---|
| cabeçalho | hidpi.h |