Menggunakan Objek Perangkat Kontrol

Objek perangkat kontrol adalah objek perangkat kerangka kerja yang tidak mendukung operasi Plug and Play (PnP) atau manajemen daya. Driver dapat menggunakan objek perangkat kontrol untuk mewakili perangkat virtual khusus perangkat lunak atau perangkat keras warisan (yaitu, perangkat yang tidak menyediakan kemampuan PnP atau manajemen daya).

Driver yang membuat objek perangkat kontrol juga biasanya membuat tautan simbolis untuk objek perangkat. Aplikasi dapat mengirim permintaan I/O ke objek perangkat kontrol dengan meneruskan nama tautan simbolis ke elemen API, seperti fungsi Microsoft Win32 CreateFile .

Kerangka kerja tidak melampirkan objek perangkat kontrol ke tumpukan perangkat. Oleh karena itu, ketika aplikasi mengirim permintaan I/O ke objek perangkat kontrol, manajer I/O mengirimkan permintaan langsung ke driver yang membuat objek perangkat kontrol, alih-alih ke driver di bagian atas tumpukan. (Namun, driver tambahan dapat memanggil IoAttachDevice untuk melampirkan objek perangkat di atas objek perangkat kontrol. Dalam hal ini, driver tambahan menerima permintaan I/O terlebih dahulu.)

Penggunaan Objek Perangkat Kontrol

Dua penggunaan umum untuk perangkat kontrol adalah:

1. Driver filter untuk perangkat PnP, jika driver mendukung serangkaian kode kontrol I/O kustom untuk digunakan aplikasi.

   Jika aplikasi mencoba mengirim kode kontrol I/O kustom ke bagian atas tumpukan driver (dengan menggunakan, misalnya, nama tautan simbolis antarmuka perangkat), driver di atas driver filter mungkin gagal permintaan I/O jika driver tidak mengenali kode kontrol I/O kustom. Untuk menghindari masalah ini, pengandar filter dapat membuat objek perangkat kontrol. Aplikasi dapat menggunakan nama tautan simbolis objek perangkat kontrol untuk mengirim kode kontrol I/O langsung ke driver filter.

   (Perhatikan bahwa cara yang lebih baik bagi pengemudi filter untuk menghindari masalah adalah bertindak sebagai pengemudi bus dan menghitung perangkat anak yang beroperasi dalam mode mentah. Dengan kata lain, untuk setiap perangkat yang didukung driver filter, driver dapat membuat objek perangkat fisik (PDO) yang tidak memerlukan driver fungsi. Driver memanggil WdfPdoInitAssignRawDevice dan WdfDeviceInitAssignName untuk setiap perangkat ini, dan aplikasi dapat mengidentifikasi perangkat berdasarkan nama saat mengirim kode kontrol I/O kustom.)

2. Driver untuk perangkat yang tidak mendukung PnP.

   Driver tersebut harus menggunakan objek perangkat kontrol, karena objek perangkat untuk perangkat tersebut tidak berada di tumpukan perangkat dan tidak menyediakan kemampuan PnP. Untuk informasi selengkapnya tentang mendukung perangkat non-PnP, lihat Menggunakan Kernel-Mode Driver Framework dengan Driver Non-PnP.

Membuat Objek Perangkat Kontrol

Untuk membuat objek perangkat kontrol, driver harus:

1. Panggil WdfControlDeviceInitAllocate untuk mendapatkan struktur WDFDEVICE_INIT .

2. Panggil metode inisialisasi objek, sesuai kebutuhan, untuk menginisialisasi struktur WDFDEVICE_INIT. Driver hanya dapat memanggil metode inisialisasi berikut:

   • WdfControlDeviceInitSetShutdownNotification
   • WdfDeviceInitAssignName
   • WdfDeviceInitAssignSDDLString
   • WdfDeviceInitAssignWdmIrpPreprocessCallback
   • WdfDeviceInitSetCharacteristics
   • WdfDeviceInitSetDeviceClass
   • WdfDeviceInitSetExclusive
   • WdfDeviceInitSetFileObjectConfig
   • WdfDeviceInitSetIoInCallerContextCallback
   • WdfDeviceInitSetIoType
   • WdfDeviceInitSetRequestAttributes

3. Panggil WdfDeviceCreate, yang menggunakan konten struktur WDFDEVICE_INIT untuk membuat objek perangkat kerangka kerja.

4. Selesaikan operasi inisialisasi berikut:

   • Buat antrean I/O default untuk perangkat, jika diperlukan.
   • Panggil WdfDeviceConfigureRequestDispatching, jika diperlukan.
   • Panggil WdfDeviceCreateSymbolicLink untuk membuat nama tautan simbolis yang dapat digunakan aplikasi untuk mengakses perangkat kontrol.

5. Panggil WdfControlFinishInitializing.

Aturan untuk Menggunakan Objek Perangkat Kontrol

Driver yang membuat objek perangkat kontrol harus mematuhi aturan berikut:

• Driver tidak dapat meneruskan handel objek perangkat kontrol ke metode kerangka kerja yang menghitung perangkat anak.

• Driver tidak dapat meneruskan handel objek perangkat kontrol ke metode kerangka kerja yang mendukung antarmuka perangkat.

• Driver dapat membuat antrean I/O dan mendaftarkan penangan permintaan untuk antrean, tetapi kerangka kerja tidak memungkinkan antrean dikelola daya.

• Driver dapat membuat objek file untuk mengontrol objek perangkat.

Penamaan Objek Perangkat Kontrol

Semua objek perangkat kontrol harus diberi nama. Biasanya, driver Anda akan memanggil WdfDeviceInitAssignName untuk menetapkan nama perangkat dan kemudian memanggil WdfDeviceCreateSymbolicLink untuk membuat nama tautan simbolis yang dapat digunakan aplikasi untuk mengakses objek.

Jika driver Anda tidak memanggil WdfDeviceInitAssignName untuk menetapkan nama perangkat, kerangka kerja secara otomatis menghasilkan nama untuk perangkat kontrol--tetapi driver Anda tidak dapat memanggil WdfDeviceCreateSymbolicLink.

Driver Anda dapat memanggil WdfDeviceInitSetDeviceClass untuk menentukan kelas penyiapan perangkat untuk perangkat kontrol. Kelas penyiapan perangkat mengidentifikasi bagian registri yang berisi informasi yang disediakan administrator tentang perangkat yang termasuk dalam kelas penyiapan. Untuk informasi selengkapnya tentang memanggil WdfDeviceInitSetDeviceClass, lihat Mengontrol Akses Perangkat di Driver Framework-Based.

Menerima Pemberitahuan Pematian Sistem

Karena objek perangkat kontrol tidak mendukung PnP, driver Anda tidak dapat mendaftarkan fungsi panggilan balik yang memberi tahu driver ketika status daya perangkat berubah. Namun, driver dapat memanggil WdfControlDeviceInitSetShutdownNotification untuk mendaftarkan fungsi panggilan balik EvtDeviceShutdownNotification . Fungsi panggilan balik ini menginformasikan driver ketika sistem akan kehilangan dayanya.

Menghapus Objek Perangkat Kontrol

Beberapa driver harus menghapus objek perangkat kontrol mereka sebelum driver dibongkar, sebagai berikut:

• Jika driver Anda membuat objek perangkat kontrol (yang tidak mendukung PnP atau manajemen daya), dan jika driver juga membuat objek perangkat kerangka kerja yang mendukung PnP dan manajemen daya, driver akhirnya harus memanggil WdfObjectDelete di IRQL = PASSIVE_LEVEL untuk menghapus objek perangkat kontrol.

  Jika driver membuat kedua jenis objek perangkat, sistem operasi tidak dapat membongkar driver Anda sampai driver telah menghapus objek perangkat kontrol.

  Namun, driver tidak boleh menghapus objek perangkat kontrol sampai setelah kerangka kerja menghapus objek perangkat lainnya. Untuk menentukan kapan kerangka kerja telah menghapus objek perangkat lainnya, driver Anda harus menyediakan fungsi EvtCleanupCallback untuk objek tersebut.

• Jika driver Anda membuat objek perangkat kontrol tetapi tidak membuat objek perangkat kerangka kerja yang mendukung PnP dan manajemen daya, driver tidak harus menghapus objek perangkat kontrol.

  Dalam hal ini, kerangka kerja menghapus objek perangkat kontrol setelah fungsi panggilan balik EvtDriverUnload driver kembali.