Invio di report HID

Questa sezione descrive come le applicazioni in modalità utente e i driver in modalità kernel inviano report HID a una raccolta HID.

Invio di report HID da applicazioni User-Mode

Un'applicazione in modalità utente deve usare WriteFile come approccio principale per inviare continuamente report di output a una raccolta HID. Un'applicazione può anche usare HidD_SetXxx routine per inviare report di output e report delle funzionalità a una raccolta. Tuttavia, un'applicazione deve utilizzare queste routine solo per impostare lo stato corrente di una raccolta. Alcuni dispositivi potrebbero non supportare HidD_SetOutputReport e non risponderanno se questa routine viene usata.

Uso di WriteFile

Un'applicazione deve usare richieste di scrittura per inviare report di output a una raccolta HID. Dopo che un'applicazione in modalità utente ha creato un report di output, può inviare un report di output a una raccolta usando WriteFile.

Uso di routine HidD_SetXxx

Un'applicazione può usare le routine di supporto HIDClass seguenti per inviare report HID a una raccolta HID:

HidD_SetOutputReport Invia un report di output a una raccolta HID (Windows XP e versioni successive).

HidD_SetFeature Invia un report delle funzionalità a una raccolta HID.

Invio di report HID tramite driver Kernel-Mode

Un driver in modalità kernel deve usare IRP_MJ_WRITE richieste come approccio principale per inviare continuamente report di output a una raccolta HID. I driver possono anche usare IOCTL_HID_SET_Xxx richieste per inviare report di output e report delle funzionalità a una raccolta. Tuttavia, un driver deve usare queste richieste di I/O solo per impostare lo stato corrente di una raccolta. Alcuni dispositivi potrebbero non supportare IOCTL_HID_SET_OUTPUT_REPORT e non risponderanno se questa richiesta viene usata.

Uso delle richieste di IRP_MJ_WRITE

Driver e driver windows 2000 non WDM per Windows XP e versioni successive possono usare un singolo IRP per tutte le richieste di scrittura inviate a una raccolta. Tuttavia, i driver WDM di Windows 2000 devono allocare un nuovo IRP per ogni richiesta di scrittura. Per altre informazioni su come usare e riutilizzare i provider di integrazione, vedere Gestione dei runtime di integrazione e riutilizzo dei runtime di integrazione.

Se il driver riutilizza un IRP di scrittura, 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 essere completato e liberare l'IRP chiamando IoCompleteRequest e IoFreeIrp. Ad esempio, un driver potrebbe in genere completare e liberare l'IRP nella routine Scarica oppure dopo la rimozione di un dispositivo.

Se un driver usa un IRP per una sola richiesta di scrittura, la routine IoCompletion di IRP deve essere completata e liberata e restituita STATUS_SUCCESS.

Prima di inviare un report di output, un driver deve prima inizializzare e impostare un buffer del report di output, come descritto in Inizializzazione di report HID. Il driver deve quindi usare un MDL per eseguire il mapping del buffer del report di output per una richiesta di scrittura. Un driver chiama IoAllocateMdl per allocare MDL per un report di output e imposta un membro Irp-MdlAddress> di scrittura sull'indirizzo MDL del buffer del report di output. 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 di scrittura, 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.Write.Length
Impostare sulla lunghezza, in byte, di un report di output. Deve essere impostata sulla lunghezza dei report di output di un insieme HID, come specificato dal membro OutputReportByteLength della struttura HIDP_CAPS di una raccolta.

Parameters.Write.Key
Imposta su zero.

Parameters.Write.ByteOffset.QuadPart
Imposta su zero.

MajorFunction
Impostare su IRP_MJ_WRITE.

FileObject
Impostare sul puntatore all'oggetto file che rappresenta il file aperto nell'insieme HID.

Uso delle richieste di IOCTL_HID_SET_Xxx

Un driver può anche usare le richieste di I/O seguenti per inviare report di output e funzionalità a una raccolta HID:

IOCTL_HID_SET_OUTPUT_REPORT
Invia un report di output a una raccolta (Windows XP e versioni successive).

IOCTL_HID_SET_FEATURE
Invia un report delle funzionalità a una raccolta.