IOCTL_HID_GET_INDEXED_STRING IOCTL (hidclass.h)

Artikel
08/07/2023

Permintaan IOCTL_HID_GET_INDEXED_STRING mendapatkan string yang disematkan tertentu dari koleksi tingkat atas. String yang diambil adalah string karakter lebar yang dihentikan NULL dalam format yang dapat dibaca manusia.

Untuk informasi umum tentang perangkat HIDClass, lihat Koleksi HID.

Kode utama

IRP_MJ_DEVICE_CONTROL

Buffer input

Parameters.DeviceIoControl.InputBufferLength di lokasi tumpukan I/O IRP menunjukkan ukuran dalam byte buffer input di lokasi yang ditunjukkan oleh Irp-AssociatedIrp.SystemBuffer>.

Parameters.DeviceIoControl.OutputBufferLength di lokasi tumpukan I/O IRP menunjukkan ukuran, dalam byte, dari buffer output. Jika buffer output tidak cukup besar untuk menahan seluruh string tersemat yang dihentikan NULL, permintaan tidak mengembalikan apa pun di buffer output.

Penanganan minidriver: IOCTL_HID_GET_INDEXED_STRING menggunakan dua buffer input.

Parameters.DeviceIoControl.OutputBufferLength di lokasi tumpukan I/O IRP menunjukkan ukuran, dalam byte, dari buffer output di lokasi yang ditunjukkan oleh Irp-MdlAddress>. Jika buffer output tidak cukup besar untuk menahan seluruh string tersemat yang dihentikan NULL, permintaan tidak mengembalikan apa pun di buffer output. Jumlah karakter maksimum yang mungkin dalam string yang disematkan adalah spesifik perangkat. Untuk perangkat USB, panjang string maksimum adalah 126 karakter lebar (tidak termasuk karakter NULL yang mengakhiri).

Parameters.DeviceIoControl.Type3InputBuffer berisi nilai INT yang menjelaskan string yang akan diambil. Dua byte yang paling signifikan dari nilai INT berisi ID bahasa (misalnya, nilai 1033 menunjukkan bahasa Inggris). Dua byte yang paling tidak signifikan dari nilai INT berisi indeks string.

Panjang buffer input

Parameters.DeviceIoControl.InputBufferLength harus >= sizeof(ULONG) dan harus berisi indeks string yang akan diambil.

Untuk Parameters.DeviceIoControl.OutputBufferLength, jumlah karakter maksimum yang mungkin dalam string yang disematkan adalah spesifik perangkat. Untuk perangkat USB, panjang string maksimum adalah 126 karakter lebar (tidak termasuk karakter NULL yang mengakhiri).

Buffer output

Irp->MdlAddress menunjuk ke buffer untuk menerima string yang diambil (string karakter lebar yang dihentikan NULL).

Penanganan minidriver: Irp-MdlAddress> menunjuk ke buffer untuk menerima string yang diambil (string karakter lebar yang dihentikan NULL). Perhatikan bahwa tidak seperti kebanyakan runtime integrasi kontrol perangkat untuk minidriver HID, IRP ini tidak menggunakan buffering METHOD_NEITHER. Secara khusus, ini harus dibedakan dari IOCTL_HID_GET_STRING yang buffer outputnya diidentifikasi oleh Irp-UserBuffer>.

Panjang buffer output

Panjang string yang diambil (string karakter lebar yang dihentikan NULL). Buffer yang disediakan harus <= 4093 byte (2^12 – 3).

Blok status

Driver kelas HID mengatur bidang Irp-IoStatus> berikut:

Informasi diatur ke jumlah byte yang ditransfer dari perangkat.
Status diatur ke STATUS_SUCCESS jika transfer selesai tanpa kesalahan. Jika tidak, kode ini diatur ke kode kesalahan NTSTATUS yang sesuai.