função HidP_GetUsageValueArray (hidpi.h)

Artigo
02/07/2025

A rotina de HidP_GetUsageValueArray extrai os dados associados a um controle HID matriz de valor de uso de um relatório HID.

Sintaxe

NTSTATUS HidP_GetUsageValueArray(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USAGE                UsagePage,
  [in]      USHORT               LinkCollection,
  [in]      USAGE                Usage,
  [in, out] PCHAR                UsageValue,
  [in]      USHORT               UsageValueByteLength,
  [in]      PHIDP_PREPARSED_DATA PreparsedData,
  [in]      PCHAR                Report,
  [in]      ULONG                ReportLength
);

Parâmetros

[in] ReportType

Especifica um valor de enumerador HIDP_REPORT_TYPE que identifica o tipo de relatório.

[in] UsagePage

Especifica a página de uso da matriz de valor de uso.

[in] LinkCollection

Especifica a coleção de links que contém a matriz de valor de uso. Se linkCollection não for zero, a rotina só procurará uma matriz de valor de uso nesta coleção de links; caso contrário, se LinkCollection for zero, a rotina procurará uma matriz de valor de uso no coleção de nível superior associada a PreparsedData.

[in] Usage

Especifica o uso da matriz de valor de uso.

[in, out] UsageValue

Ponteiro para um buffer alocado por chamador no qual a rotina retorna os dados associados à matriz de valor de uso.

[in] UsageValueByteLength

Especifica o comprimento, em bytes, do buffer em UsageValue .

[in] PreparsedData

Ponteiro para os dados pré-preparados de uma coleção de nível superior.

[in] Report

Ponteiro para um relatório que contém valores.

[in] ReportLength

Especifica o comprimento, em bytes, do relatório localizado em Report.

Valor de retorno

HidP_GetUsageValueArray retorna um dos seguintes valores de status:

Código de retorno	Descrição
HIDP_STATUS_SUCCESS	A rotina retornou com êxito os dados do valor.
HIDP_INVALID_REPORT_LENGTH	O comprimento do relatório não é válido.
HIDP_INVALID_REPORT_TYPE	O tipo de relatório especificado não é válido.
HIDP_STATUS_NOT_VALUE_ARRAY	O uso solicitado não é uma matriz de valor de uso.
HIDP_STATUS_BUFFER_TOO_SMALL	O buffer UsageValue é muito pequeno para manter o uso solicitado.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	A coleção contém uma matriz de valor de uso na página de uso especificada em um relatório do tipo especificado, mas não há esses usos no relatório especificado.
HIDP_STATUS_INVALID_PREPARSED_DATA	Os dados pré-parados não são válidos.
HIDP_STATUS_USAGE_NOT_FOUND	A coleção não contém uma matriz de valor de uso na página de uso especificada em nenhum relatório do tipo de relatório especificado.

Observações

O tamanho necessário, em bytes, de UsageValueByteLength é determinado multiplicando os membros BitSize e ReportCount membros da estrutura de HIDP_VALUE_CAPS da matriz de valor de uso e arredondando o resultado para o byte mais próximo.

HidP_GetUsageValueArray define o buffer UsageValue em ordem little-endian, começando com o bit menos significativo dos dados do uso. Os dados não são alinhados por bytes e são deslocados de modo que o bit menos significativo dos dados esteja localizado no primeiro bit do buffer UsageValue.

HidP_GetUsageValueArray foi projetado para extrair todos os valores de uso para um uso cuja contagem de relatórios é maior que 1. Para extrair um uso cuja contagem de relatórios é igual a 1, use HidP_GetUsageValue.

Para obter mais informações, consulte coleções HID.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível no Windows 2000 e versões posteriores do Windows.
da Plataforma de Destino	Universal
cabeçalho	hidpi.h (inclua Hidpi.h)
biblioteca	Hidparse.lib
IRQL	<= DISPATCH_LEVEL