Bagikan melalui

Mendapatkan Laporan HID

  • Artikel

Artikel ini menjelaskan bagaimana aplikasi mode pengguna dan driver mode kernel mendapatkan laporan HID dari koleksi HID.

Mendapatkan Laporan HID oleh aplikasi mode pengguna

Bagian ini membahas perolehan laporan input HID atau laporan fitur HID, oleh aplikasi mode pengguna menggunakan ReadFile atau HidD_Get rutinitas Xxx.

Namun, aplikasi hanya boleh menggunakan rutinitas Xxx HidD_Getuntuk mendapatkan status perangkat saat ini. Jika aplikasi mencoba menggunakan HidD_GetInputReport untuk terus mendapatkan laporan input, laporan dapat hilang. Selain itu, beberapa perangkat tidak mendukung HidD_GetInputReport dan menjadi tidak responsif jika rutinitas ini digunakan.

Menggunakan ReadFile

Aplikasi menggunakan handel file terbuka yang diperolehnya dengan menggunakan CreateFile untuk membuka file pada koleksi. Ketika aplikasi memanggil ReadFile, aplikasi tidak perlu menentukan I/O yang tumpang tindih karena buffer Driver Klien HID melaporkan dalam buffer cincin. Namun, aplikasi dapat menggunakan I/O yang tumpang tindih untuk memiliki lebih dari satu permintaan baca yang luar biasa.

Menggunakan Rutinitas HidD_GetXxx

Aplikasi dapat menggunakan rutinitas dukungan HIDClass berikut untuk mendapatkan laporan input dan laporan fitur terbaru dari koleksi HID:

  • HidD_GetInputReport: Mengembalikan laporan input dari koleksi HID (Windows XP dan versi yang lebih baru).
  • HidD_GetFeature: Mengembalikan laporan fitur dari koleksi HID.

Aplikasi dapat meminta pengembalian laporan tertentu. Untuk mengambil laporan tertentu menggunakan rutinitas HidD_GetXxx, aplikasi mengalokasikan buffer output laporan, menginisialisasi buffer nol, dan mengatur byte pertama dalam buffer ke ID laporan tertentu. Untuk informasi selengkapnya, lihat Menginisialisasi Laporan HID.

Mendapatkan Laporan HID oleh driver mode kernel

Bagian ini membahas bagaimana driver mode kernel harus menggunakan permintaan IRP_MJ_READ sebagai pendekatan utamanya untuk terus mendapatkan laporan input HID.

Permintaan baca berturut-turut mengembalikan laporan input dalam urutan diterimanya dari koleksi. Driver juga dapat menggunakan permintaan IOCTL_HID_GET_Xxx untuk mendapatkan laporan input dan fitur. Namun, driver hanya boleh menggunakan permintaan IOCTL_HID_GET_Xxx untuk mendapatkan status perangkat saat ini. Jika driver mencoba menggunakan IOCTL_HID_GET_INPUT_REPORT untuk terus mendapatkan laporan input, laporan dapat hilang. Selain itu, beberapa perangkat tidak mendukung IOCTL_HID_GET_INPUT_REPORT dan menjadi tidak responsif jika permintaan ini digunakan.

Menggunakan Permintaan IRP_MJ_READ

Untuk informasi umum tentang cara menggunakan dan menggunakan kembali paket permintaan I/O (IRP), lihat Menangani IRP dan Menggunakan kembali RUN.

Jika driver menggunakan kembali IRP, rutinitas IoCompletion IRP harus menyelesaikan permintaan dengan status STATUS_MORE_PROCESSING_REQUIRED (dan tidak membebaskan IRP). Ketika driver tidak lagi memerlukan IRP, driver harus menyelesaikan dan membebaskan IRP dengan memanggil IoCompleteRequest dan IoFreeIrp. Misalnya, driver biasanya dapat menyelesaikan dan membebaskan IRP dalam rutinitas Bongkar , atau setelah perangkat dihapus.

Jika driver menggunakan IRP hanya untuk satu permintaan baca, rutinitas IoCompletion IRP harus menyelesaikan dan membebaskan IRP, dan mengembalikan STATUS_SUCCESS.

Sebelum driver dapat meminta laporan input, driver harus terlebih dahulu mengalokasikan buffer laporan input yang diinisialisasi nol dari kumpulan memori yang tidak dipagasi. Ukuran, dalam byte, buffer ditentukan oleh anggota InputReportByteLength dari struktur HIDP_CAPS koleksi HID. Driver kemudian harus menggunakan MDL untuk memetakan buffer laporan input untuk permintaan baca. Driver memanggil IoAllocateMdl untuk mengalokasikan MDL untuk buffer laporan input, dan mengatur anggota Irp-MdlAddress> IRP baca ke alamat MDL buffer laporan input. Driver harus membebaskan buffer laporan dan MDL ketika tidak lagi diperlukan.

Selain mengatur alamat MDL IRP baca, driver juga harus mengatur lokasi tumpukan I/O driver tingkat bawah berikutnya. Driver mendapatkan akses ke lokasi tumpukan I/O driver tingkat bawah berikutnya dengan memanggil IoGetNextIrpStackLocation. Driver mengatur anggota lokasi tumpukan I/O berikut:

  • Parameters.Read.Length: Atur ke ukuran, dalam byte, dari buffer baca. Ukurannya harus lebih besar dari atau sama dengan nilai yang ditentukan oleh anggota InputReportByteLength dari struktur HIDP_CAPS koleksi HID.
  • Parameters.Read.Key: Atur ke nol.
  • Parameters.Read.ByteOffset.QuadPart: Atur ke nol.
  • MajorFunction: Atur ke IRP_MJ_READ.
  • FileObject: Atur ke penunjuk objek file yang mewakili file terbuka pada koleksi HID.

Setelah driver mendapatkan laporan input, driver dapat mengakses data kontrol, seperti yang dijelaskan dalam Menginterpretasikan Laporan HID.

Menggunakan Permintaan IOCTL_HID_GET_Xxx

Driver dapat menggunakan permintaan I/O berikut untuk mendapatkan laporan input dan fitur terbaru dari koleksi HID:

  • IOCTL_HID_GET_INPUT_REPORT: Mengembalikan laporan input dari koleksi HID (Windows XP dan versi yang lebih baru).
  • IOCTL_HID_GET_FEATURE: Mengembalikan laporan fitur dari koleksi HID.

Driver dapat meminta pengembalian laporan tertentu. Untuk mengambil laporan tertentu menggunakan permintaan I/O ini, driver terlebih dahulu mengalokasikan buffer laporan output, lalu menginisialisasi buffer nol, dan mengatur byte pertama dalam buffer ke ID laporan tertentu.

Untuk informasi selengkapnya, lihat Menginterpretasikan Laporan HID.