IOCTL_HID_GET_STRING IOCTL (hidport.h)

Articolo
02/29/2024

La richiesta di IOCTL_HID_GET_STRING ottiene un ID produttore, un ID prodotto o un numero di serie per una raccolta di livello superiore. La stringa recuperata è una stringa di caratteri wide con terminazione NULL in un formato leggibile.

Per informazioni generali sui dispositivi HIDClass, vedere Raccolte HID.

Codice principale

IRP_MJ_DEVICE_CONTROL

Buffer di input

IOCTL_HID_GET_STRING usa due buffer di input.

Parameters.DeviceIoControl.OutputBufferLength nella posizione dello stack I/O dell'IRP indica le dimensioni, in byte, del buffer di output bloccato in Irp-UserBuffer>. Se il buffer di output non è abbastanza grande per contenere l'intera stringa incorporata con terminazione NULL, la richiesta restituisce nulla nel buffer di output. Il numero massimo possibile di caratteri in una stringa incorporata è specifico del dispositivo. Per i dispositivi USB, la lunghezza massima della stringa è di 126 caratteri wide (non incluso il carattere NULL terminante).

Parameters.DeviceIoControl.Type3InputBuffer nella posizione dello stack I/O dell'IRP contiene un valore composito. I due byte più significativi contengono l'ID lingua della stringa da recuperare. I due byte meno significativi contengono uno dei tre valori costanti seguenti:

HID_STRING_ID_IMANUFACTURER
HID_STRING_ID_IPRODUCT
HID_STRING_ID_ISERIALNUMBER

Il minidriver HID determina quale di queste tre costanti è presente nei due byte inferiori del buffer di input, quindi deve recuperare l'indice stringa corrispondente dal descrittore del dispositivo. Le informazioni sul descrittore del dispositivo vengono archiviate nell'estensione del dispositivo di una raccolta di livello superiore associata al dispositivo.

È importante non confondere queste tre costanti con gli indici stringa effettivi degli ID. Queste costanti rappresentano gli offset nel descrittore del dispositivo in cui è possibile trovare gli indici stringa corrispondenti.

Ad esempio, HID_STRING_ID_IMANUFACTURER indica la posizione nel descrittore del dispositivo in cui viene trovato l'indice per l'ID produttore. Questo indice, a sua volta, funge da offset nel descrittore stringa in cui si trova la forma leggibile del produttore.

Lunghezza del buffer di input

Dimensioni dell'outputBufferLength e delle dimensioni di Type3InputBuffer.

Buffer di output

Il minidriver HID riempie il buffer in Irp-UserBuffer> con la stringa richiesta (stringa di caratteri wide con terminazione NULL).

Lunghezza del buffer di output

Dimensioni dell'oggetto UserBuffer.

Blocco dello stato

I minidriver HID che eseguono l'I/O al dispositivo impostano i campi seguenti di Irp-IoStatus>:

Le informazioni vengono impostate sul numero di byte trasferiti dal dispositivo.
Lo stato è impostato su STATUS_SUCCESS se il trasferimento è stato completato senza errore. In caso contrario, è impostato su un codice di errore NTSTATUS appropriato.

I minidriver HID che chiamano altri driver con questo IOCTL per eseguire l'I/O nel dispositivo, devono assicurarsi che il campo Informazioni del blocco di stato sia corretto e non modificare il contenuto del campo Stato .