IOCTL_HID_GET_STRING IOCTL (hidport.h)

Artikel
08/07/2023

Permintaan IOCTL_HID_GET_STRING mendapatkan ID produsen, ID produk, atau nomor seri untuk 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

IOCTL_HID_GET_STRING menggunakan dua buffer input.

Parameters.DeviceIoControl.OutputBufferLength di lokasi tumpukan I/O IRP menunjukkan ukuran, dalam byte, dari buffer output yang dikunci di Irp-UserBuffer>. 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 di lokasi tumpukan I/O IRP berisi nilai komposit. Dua byte yang paling signifikan berisi ID bahasa string yang akan diambil. Dua byte yang paling tidak signifikan berisi salah satu dari tiga nilai konstanta berikut:

HID_STRING_ID_IMANUFACTURER
HID_STRING_ID_IPRODUCT
HID_STRING_ID_ISERIALNUMBER

Minidriver HID menentukan mana dari ketiga konstanta ini yang ada di dua byte yang lebih rendah dari buffer input, maka harus mengambil indeks string yang sesuai dari deskriptor perangkat. Informasi deskriptor perangkat disimpan di ekstensi perangkat dari koleksi tingkat atas yang terkait dengan perangkat.

Penting untuk tidak membingungkan ketiga konstanta ini dengan indeks string id yang sebenarnya. Konstanta ini mewakili offset dalam deskriptor perangkat tempat indeks string yang sesuai dapat ditemukan.

Misalnya, HID_STRING_ID_IMANUFACTURER menunjukkan lokasi di deskriptor perangkat tempat indeks untuk ID produsen ditemukan. Indeks ini, pada gilirannya, berfungsi sebagai offset ke dalam deskriptor string tempat bentuk ID produsen yang dapat dibaca manusia berada.

Panjang buffer input

Ukuran OutputBufferLength dan ukuran Type3InputBuffer.

Buffer output

Minidriver HID mengisi buffer di Irp-UserBuffer> dengan string yang diminta (string karakter lebar yang dihentikan NULL).

Panjang buffer output

Ukuran UserBuffer.

Blok status

Minidriver HID yang melakukan I/O ke perangkat 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, ini diatur ke kode kesalahan NTSTATUS yang sesuai.

Minidriver HID yang memanggil driver lain dengan IOCTL ini untuk melakukan I/O ke perangkat mereka, harus memastikan bahwa bidang Informasi blok status sudah benar dan tidak mengubah konten bidang Status .