funzione HidP_GetUsageValueArray (hidpi.h)

Articolo
02/07/2025

La routine HidP_GetUsageValueArray estrae i dati associati a un controllo HID matrice di valori di utilizzo da un report HID.

Sintassi

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
);

Parametri

[in] ReportType

Specifica un valore enumeratore HIDP_REPORT_TYPE che identifica il tipo di report.

[in] UsagePage

Specifica la pagina di utilizzo della matrice di valori di utilizzo.

[in] LinkCollection

Specifica la raccolta di collegamenti che contiene la matrice di valori di utilizzo. Se LinkCollection è diverso da zero, la routine cerca solo una matrice di valori di utilizzo in questa raccolta di collegamenti; in caso contrario, se LinkCollection è zero, la routine cerca una matrice di valori di utilizzo nella raccolta di primo livello associata a PreparsedData.

[in] Usage

Specifica l'utilizzo della matrice di valori di utilizzo.

[in, out] UsageValue

Puntatore a un buffer allocato dal chiamante in cui la routine restituisce i dati associati alla matrice di valori di utilizzo.

[in] UsageValueByteLength

Specifica la lunghezza, in byte, del buffer in UsageValue.

[in] PreparsedData

Puntatore a una raccolta di livello superiore prepara i dati.

[in] Report

Puntatore a un report che contiene valori.

[in] ReportLength

Specifica la lunghezza, in byte, del report che si trova in Report.

Valore restituito

HidP_GetUsageValueArray restituisce uno dei valori di stato seguenti:

Codice restituito	Descrizione
HIDP_STATUS_SUCCESS	La routine ha restituito correttamente i dati del valore.
HIDP_INVALID_REPORT_LENGTH	La lunghezza del report non è valida.
HIDP_INVALID_REPORT_TYPE	Il tipo di report specificato non è valido.
HIDP_STATUS_NOT_VALUE_ARRAY	L'utilizzo richiesto non è una matrice di valori di utilizzo.
HIDP_STATUS_BUFFER_TOO_SMALL	Il buffer UsageValue è troppo piccolo per contenere l'utilizzo richiesto.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	La raccolta contiene una matrice di valori di utilizzo nella pagina di utilizzo specificata in un report del tipo specificato, ma non esistono tali utilizzi nel report specificato.
HIDP_STATUS_INVALID_PREPARSED_DATA	I dati pronti non sono validi.
HIDP_STATUS_USAGE_NOT_FOUND	La raccolta non contiene una matrice di valori di utilizzo nella pagina di utilizzo specificata in alcun report del tipo di report specificato.

Osservazioni

Le dimensioni richieste, in byte, di UsageValueByteLength sono determinate moltiplicando insieme i BitSize e ReportCount della struttura HIDP_VALUE_CAPS della matrice di valori di utilizzo e arrotondando il risultato al byte più vicino.

HidP_GetUsageValueArray imposta il buffer UsageValue in ordine little-endian, a partire dal bit meno significativo dei dati di utilizzo. I dati non sono allineati ai byte e vengono spostati in modo che il bit meno significativo dei dati si trovi al primo bit del buffer UsageValue.

HidP_GetUsageValueArray è progettato per estrarre tutti i valori di utilizzo per un utilizzo il cui numero di report è maggiore di 1. Per estrarre un utilizzo il cui numero di report è uguale a 1, usare HidP_GetUsageValue.

Per altre informazioni, vedere raccolte HID.

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile in Windows 2000 e versioni successive di Windows.
piattaforma di destinazione	Universale
intestazione	hidpi.h (include Hidpi.h)
libreria	Hidparse.lib
IRQL	<= DISPATCH_LEVEL