Recupero di report HID

Questo articolo descrive come le applicazioni in modalità utente e i driver in modalità kernel ottengono report HID da una raccolta HID.

Recupero di report HID da applicazioni in modalità utente

Questa sezione illustra l'acquisizione di report di input HID o report delle funzionalità HID, da applicazioni in modalità utente che usano ReadFile o le routine HidD_GetXxx.

Tuttavia, un'applicazione deve usare solo le routine HidD_GetXxx per ottenere lo stato corrente di un dispositivo. Se un'applicazione tenta di usare HidD_GetInputReport per ottenere continuamente report di input, i report possono andare persi. Inoltre, alcuni dispositivi non supportano HidD_GetInputReport e non rispondono se viene usata questa routine.

Uso di ReadFile

Un'applicazione usa l'handle di file aperto ottenuto usando CreateFile per aprire un file nella raccolta. Quando l'applicazione chiama ReadFile, non è necessario specificare operazioni di I/O sovrapposte perché i buffer dei driver client HID in un buffer circolare. Tuttavia, un'applicazione può usare operazioni di I/O sovrapposte per avere più richieste di lettura in sospeso.

Uso di routine HidD_GetXxx

Un'applicazione può usare le routine di supporto HIDClass seguenti per ottenere i report di input e i report delle funzionalità più aggiornati da una raccolta HID:

• HidD_GetInputReport: restituisce un report di input da una raccolta HID (Windows XP e versioni successive).
• HidD_GetFeature: restituisce un report delle funzionalità da una raccolta HID.

Un'applicazione può richiedere la restituzione di un report specifico. Per recuperare un report specifico utilizzando HidD_GetXxx routine, l'applicazione alloca il buffer di output del report, inizializza il buffer senza inizializzare il buffer e imposta il primo byte nel buffer sull'ID del report specifico. Per altre informazioni, vedere Inizializzazione di report HID.

Recupero di report HID da driver in modalità kernel

In questa sezione viene illustrato come usare un driver in modalità kernel IRP_MJ_READ richieste come approccio principale per ottenere continuamente report di input HID.

Le richieste di lettura consecutive restituiscono report di input nell'ordine in cui sono stati ricevuti dalla raccolta. Il driver può anche usare IOCTL_HID_GET_Xxx richieste per ottenere report di input e funzionalità. Tuttavia, un driver deve usare solo IOCTL_HID_GET_Xxx richieste per ottenere lo stato corrente di un dispositivo. Se il driver tenta di usare IOCTL_HID_GET_INPUT_REPORT per ottenere continuamente report di input, i report possono andare persi. Inoltre, alcuni dispositivi non supportano IOCTL_HID_GET_INPUT_REPORT e non rispondono se viene usata questa richiesta.

Uso delle richieste di IRP_MJ_READ

Per informazioni generali su come usare e riutilizzare i pacchetti di richiesta di I/O , vedere Gestione dei runtime di integrazione e riutilizzo dei runtime di integrazione.

Se un driver riutilizza un IRP, la routine IoCompletion di IRP deve completare la richiesta con lo stato STATUS_MORE_PROCESSING_REQUIRED (e non liberare l'IRP). Quando il driver non richiede più l'IRP, deve completare e liberare l'IRP chiamando IoCompleteRequest e IoFreeIrp. Ad esempio, un driver potrebbe in genere completare e liberare l'IRP nella routine Di scaricamento o dopo la rimozione di un dispositivo.

Se un driver usa un IRP per una sola richiesta di lettura, la routine IoCompletion di IRP deve completare e liberare l'IRP e restituire STATUS_SUCCESS.

Prima che un driver possa richiedere un report di input, deve prima allocare un buffer di report di input inizializzato zero dal pool di memoria non di paging. Le dimensioni, in byte, del buffer vengono specificate dal membro InputReportByteLength della struttura HIDP_CAPS di un insieme HID. Un driver deve quindi usare un MDL per eseguire il mapping del buffer del report di input per una richiesta di lettura. Il driver chiama IoAllocateMdl per allocare il file MDL per un buffer di report di input e imposta il membro Irp-MdlAddress> di lettura sull'indirizzo MDL del buffer del report di input. Il driver deve liberare il buffer del report e il file MDL quando non sono più necessari.

Oltre a impostare l'indirizzo MDL di IRP letto, il driver deve anche impostare la posizione dello stack di I/O del driver di livello inferiore successivo. Un driver ottiene l'accesso alla posizione dello stack di I/O del driver di livello inferiore successivo chiamando IoGetNextIrpStackLocation. Il driver imposta i membri seguenti della posizione dello stack di I/O:

• Parameters.Read.Length: impostato sulle dimensioni, in byte, del buffer di lettura. Le dimensioni devono essere maggiori o uguali al valore specificato dal membro InputReportByteLength della struttura di HIDP_CAPS di un insieme HID.
• Parameters.Read.Key: impostato su zero.
• Parameters.Read.ByteOffset.QuadPart: impostato su zero.
• MajorFunction: impostare su IRP_MJ_READ.
• FileObject: impostare sul puntatore all'oggetto file che rappresenta il file aperto nell'insieme HID.

Dopo aver ottenuto un report di input, il driver può accedere ai dati di controllo, come descritto in Interpretazione dei report HID.

Uso delle richieste di IOCTL_HID_GET_Xxx

Un driver può usare le richieste di I/O seguenti per ottenere i report di input e funzionalità più aggiornati da una raccolta HID:

• IOCTL_HID_GET_INPUT_REPORT: restituisce un report di input da una raccolta HID (Windows XP e versioni successive).
• IOCTL_HID_GET_FEATURE: restituisce un report delle funzionalità da una raccolta HID.

Un driver può richiedere la restituzione di un report specifico. Per recuperare un report specifico usando queste richieste di I/O, il driver alloca innanzitutto il buffer del report di output, quindi inizializza zero il buffer e imposta il primo byte nel buffer sull'ID del report specifico.

Per altre informazioni, vedere Interpretazione dei report HID.