Interpretazione dei report HID
Questo articolo descrive come le applicazioni in modalità utente e i driver in modalità kernel usano le routine di supporto hiDClass HidP_XxxXxxper interpretare i dati di controllo in un report HID.
Estrazione dei dati di valore specificandone l'utilizzo
Per estrarre dati di valore da un report HID, un'applicazione o un driver può usare una delle routine di supporto HID seguenti:
- HidP_GetScaledUsageValue Restituisce un valore con segno e ridimensionato.
- HidP_GetUsageValue Restituisce un valore non ridimensionato in un formato senza segno o un valore scalato non compreso nell'intervallo Normal.
- HidP_GetUsageValueArray Restituisce una matrice di valori di utilizzo.
Per usare HidP_GetUsageValueArray applicazioni e driver, è necessario allocare un buffer inizializzato zero, che è sufficientemente grande da contenere la matrice di valori di utilizzo. Le dimensioni richieste in byte sono il prodotto dei membri BitSize e ReportCount della struttura di HIDP_VALUE_CAPS della matrice di valori di utilizzo, arrotondati fino al byte più vicino.
Estrazione degli utilizzi dei pulsanti impostati su ON
Per estrarre gli utilizzi HID dei pulsanti impostati su ON (1), le applicazioni e i driver chiamano una delle routine di supporto HID seguenti:
- HidP_GetButtons (o HidP_GetUsages) Restituisce l'ID utilizzo di tutti i pulsanti in una pagina di utilizzo specificata impostata su ON.
- HidP_GetButtonsEx (o HidP_GetUsagesEx) Restituisce la pagina di utilizzo e l'ID di utilizzo di tutti i pulsanti impostati su ON.
Queste routine restituiscono una matrice di tutte le informazioni sull'utilizzo per tutti i pulsanti attualmente impostati su ON. In modo implicito, i pulsanti il cui utilizzo non viene restituito da queste routine vengono impostati su OFF (zero).
Per chiamare queste routine, le applicazioni e i driver devono prima allocare e inizializzare zero il buffer usato per restituire la matrice di utilizzi dei pulsanti. Un'applicazione o un driver chiama HidP_MaxUsageListLength per determinare il numero di utilizzi dei pulsanti in una pagina di utilizzo specificata nel report. Se l'applicazione o il driver specifica una pagina di utilizzo pari a zero, la routine restituisce il numero di tutti gli utilizzi del pulsante nel report.
Le dimensioni del buffer necessarie, in byte, sono:
- (Per HidP_GetButtons) Valore restituito da HidP_MaxUsageListLength volte sizeof(USAGE)
- (Per HidP_GetButtonsEx) Valore restituito da HidP_MaxUsageListLength volte sizeof(USAGE_AND_PAGE)
Dopo che un'applicazione o un driver usa queste routine per ottenere informazioni sui pulsanti attualmente impostati su ON, può determinare la differenza tra lo stato corrente e lo stato precedente dei pulsanti chiamando una delle routine di supporto HIDClass seguenti. Queste routine restituiscono la differenza tra due matrici di informazioni sull'utilizzo:
Estrazione e impostazione dei dati di controllo in base agli indici di dati
Per usare gli indici di dati per estrarre e impostare i dati di controllo in un report HID, un'applicazione o un driver può usare le routine di supporto HIDClass seguenti:
Queste routine sono utili per un'applicazione o un driver che fornisce un servizio "aggiunto a valore". Ad esempio, uno che fornisce un'interfaccia personalizzata a tutti i controlli supportati da un dispositivo HIDClass. Microsoft DirectInput è un esempio.
Un'applicazione o un driver che chiama queste routine può ottenere e impostare in modo più efficiente tutti i valori in un report. Ad esempio, per ottenere tutti i dati di valore in base ai relativi utilizzi HID, è necessario chiamare HidP_GetUsageValue per ogni utilizzo. Tuttavia, per ottenere tutti i dati di valore in base all'indice dati, è necessario chiamare solo HidP_GetData una volta.
Un'applicazione o un driver usa gli indici di dati specificati nelle matrici di funzionalità button di una raccolta e nelle matrici di funzionalità valore di una raccolta per identificare gli utilizzi HID.
Impostazione dei dati di valore specificandone l'utilizzo
Un'applicazione o un driver può impostare un valore in un report HID inizializzato correttamente chiamando una delle routine di supporto HID seguenti:
- HidP_SetScaledUsageValue Imposta un valore con segno e ridimensionato in un report.
- HidP_SetUsageValue Imposta un valore in un report.
- HidP_SetUsageValueArray Imposta una matrice di valori di utilizzo in un report.
Impostazione dello stato del pulsante specificandone l'utilizzo
Un'applicazione o un driver può impostare lo stato dei pulsanti in un report HID inizializzato correttamente chiamando una delle routine di supporto HIDClass seguenti:
- HidP_SetButtons (o HidP_SetUsages) Imposta un set specificato di pulsanti su ON (1).
- HidP_UnsetButtons (o HidP_UnsetUsages) Imposta un set specificato di pulsanti su OFF (zero).
Estrazione e impostazione dei dati di controllo HID in base agli indici di dati
Per usare gli indici di dati per estrarre e impostare i dati di controllo in un report HID, un'applicazione o un driver può usare le routine di supporto HIDClass seguenti:
Queste routine sono utili per un'applicazione o un driver che fornisce un servizio "aggiunto a valore". Ad esempio, uno che fornisce un'interfaccia personalizzata a tutti i controlli supportati da un dispositivo HIDClass. Microsoft DirectInput è un esempio.
Un'applicazione o un driver che chiama queste routine può ottenere e impostare in modo più efficiente tutti i valori in un report. Ad esempio, per ottenere tutti i dati di valore in base ai relativi utilizzi HID, è necessario chiamare HidP_GetUsageValue per ogni utilizzo. Tuttavia, per ottenere tutti i dati di valore in base all'indice dati, è necessario chiamare solo HidP_GetData una volta.
Un'applicazione o un driver usa gli indici di dati specificati nelle matrici di funzionalità button di una raccolta e nelle matrici di funzionalità valore di una raccolta per identificare gli utilizzi HID.