Recupero di report HID

Questa sezione 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

Questo argomento illustra l'acquisizione di report di input HID o report delle funzionalità HID, tramite applicazioni in modalità utente usando ReadFile o le routine xxx di HidD_Get.

Tuttavia, un'applicazione deve usare solo le routine xxx HidD_Getper ottenere lo stato corrente di un dispositivo. Se un'applicazione tenta di usare HidD_GetInputReport per ottenere continuamente report di input, i report possono essere persi. Inoltre, alcuni dispositivi potrebbero non supportare HidD_GetInputReport e diventeranno non rispondenti se questa routine viene usata.

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 deve specificare l'I/O sovrapposta perché i buffer dei driver client HID in un buffer anello. Tuttavia, un'applicazione può usare l'I/O sovrapposta 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 le funzionalità più correnti 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 usando queste routine, l'applicazione alloca il buffer di output del report, inizializza il buffer e imposta il primo byte nel buffer sull'ID del report specifico. Per altre informazioni, vedere Inizializzazione dei report HID.

Recupero di report HID da driver in modalità kernel

Questo argomento illustra come un driver in modalità kernel deve usare IRP_MJ_READ richieste come approccio principale per ottenere continuamente report di input HID.

Le richieste di lettura consecutive restituiscono i 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 queste richieste di I/O 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 essere persi. Inoltre, alcuni dispositivi potrebbero non supportare IOCTL_HID_GET_INPUT_REPORT e diventeranno non rispondenti se questa richiesta viene usata.

Uso delle richieste di IRP_MJ_READ

I driver e i driver windows 2000 non WDM per Windows XP e versioni successive possono usare un'unica IRP per tutte le richieste di lettura in un dispositivo. Tuttavia, i driver WDM di Windows 2000 devono allocare un nuovo IRP per ogni richiesta di lettura. Per informazioni generali su come usare e riutilizzare i provider di servizi di integrazione, vedere Gestione di IRP e riutilizzo di IRP.

Se un driver riutilizza un'IRP, la routine IoCompletion di IoCompletion di IRP deve completare la richiesta con uno stato di 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 oppure dopo la rimozione di un dispositivo.

Se un driver usa un'IRP per una sola richiesta di lettura, la routine IoCompletion di IoCompletion 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 zero inizializzato dal pool di memoria non con pagine. 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 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 l'MDL quando non sono più necessari.

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

Parameters.Read.Length
Impostare sulle dimensioni, in byte, del buffer di lettura. Deve essere maggiore o uguale al valore specificato dal membro InputReportByteLength della struttura HIDP_CAPS di un insieme HID.

Parameters.Read.Key
Imposta su zero.

Parameters.Read.ByteOffset.QuadPart
Imposta su zero.

MajorFunction
Impostare su IRP_MJ_READ.

FileObject
Impostare sul puntatore a oggetti 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ù correnti 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 prima il buffer del report di output, quindi inizializza il buffer e imposta il primo byte nel buffer sull'ID del report specifico.

Per altre informazioni, vedere Interpretazione di report HID.