Share via

Menggunakan Antarmuka Perangkat di Driver UMDF

  • Artikel

Peringatan

UMDF 2 adalah versi terbaru UMDF dan supersedes UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2.

Sampel UMDF 1 yang diarsipkan dapat ditemukan di Windows 11, versi 22H2 - Pembaruan Sampel Driver Mei 2022.

Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.

Antarmuka perangkat adalah tautan simbolis ke perangkat Plug and Play (PnP) yang dapat digunakan aplikasi untuk mengakses perangkat. Aplikasi mode pengguna dapat meneruskan nama tautan simbolis antarmuka ke elemen API, seperti fungsi Microsoft Win32 CreateFile . Untuk mendapatkan nama tautan simbolis antarmuka perangkat, aplikasi mode pengguna dapat memanggil fungsi SetupDi . Untuk informasi selengkapnya tentang fungsi SetupDi, lihat Fungsi Antarmuka Perangkat SetupDi.

Setiap antarmuka perangkat milik kelas antarmuka perangkat. Misalnya, tumpukan driver untuk perangkat CD-ROM mungkin menyediakan antarmuka milik kelas GUID_DEVINTERFACE_CDROM. Salah satu driver perangkat CD-ROM akan mendaftarkan instans kelas GUID_DEVINTERFACE_CDROM untuk memberi tahu sistem dan aplikasi bahwa perangkat CD-ROM tersedia. Untuk informasi selengkapnya tentang kelas antarmuka perangkat, lihat Pengantar Antarmuka Perangkat.

Mendaftarkan Antarmuka Perangkat

Untuk mendaftarkan instans kelas antarmuka perangkat, driver berbasis UMDF dapat memanggil IWDFDevice::CreateDeviceInterface dari dalam fungsi panggilan balik IDriverEntry::OnDeviceAdd . Jika driver mendukung beberapa instans antarmuka, driver dapat menetapkan string referensi unik untuk setiap instans.

Mengaktifkan dan Menonaktifkan Antarmuka Perangkat

Jika pembuatan berhasil, kerangka kerja secara otomatis mengaktifkan dan menonaktifkan antarmuka berdasarkan status PnP perangkat.

Selain itu, driver dapat menonaktifkan dan mengaktifkan kembali antarmuka perangkat seperlunya. Misalnya, jika driver menentukan bahwa perangkatnya telah berhenti merespons, driver dapat memanggil IWDFDevice::AssignDeviceInterfaceState untuk menonaktifkan antarmuka perangkat dan melarang aplikasi mendapatkan handel baru ke antarmuka. (Handel yang ada ke antarmuka tidak terpengaruh.) Jika perangkat nantinya tersedia, driver dapat memanggil IWDFDevice::AssignDeviceInterfaceState lagi untuk mengaktifkan kembali antarmuka.

Menerima Permintaan untuk Mengakses Antarmuka Perangkat

Ketika aplikasi meminta akses ke antarmuka perangkat driver, kerangka kerja memanggil fungsi panggilan balik IQueueCallbackCreate::OnCreateFile driver. Driver dapat memanggil IWDFFile::RetrieveFileName untuk mendapatkan nama perangkat atau file yang diakses aplikasi. Jika driver menentukan string referensi saat mendaftarkan antarmuka perangkat, sistem operasi menyertakan string referensi dalam nama file atau perangkat yang dikembalikan IWDFFile::RetrieveFileName .

Membuat Peristiwa Perangkat

Driver berbasis UMDF Anda dapat membuat peristiwa kustom khusus perangkat (disebut peristiwa perangkat) dengan memanggil IWDFDevice::P ostEvent. Driver yang telah mendaftar untuk menggunakan antarmuka perangkat mana pun dapat menerima pemberitahuan tentang peristiwa kustom perangkat. Driver berbasis UMDF menerima pemberitahuan tersebut dengan menyediakan fungsi panggilan balik IRemoteInterfaceCallbackEvent::OnRemoteInterfaceEvent .

Peristiwa kustom unik untuk perangkat. Baik pengembang driver yang membuat peristiwa maupun pengembang driver yang menerima acara harus memahami arti peristiwa tersebut.

Mengakses Antarmuka Perangkat Driver Lain

Jika Anda ingin driver berbasis UMDF Anda mengirim permintaan I/O ke antarmuka perangkat yang disediakan driver lain, Anda dapat membuat target I/O jarak jauh yang mewakili antarmuka perangkat.

Pertama, driver Anda harus mendaftar untuk menerima pemberitahuan ketika antarmuka perangkat tersedia. Gunakan langkah-langkah berikut:

  1. Saat driver Anda memanggil IWDFDriver::CreateDevice, driver dapat menyediakan antarmuka IPnpCallbackRemoteInterfaceNotification . Fungsi panggilan balik IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival dari antarmuka ini menginformasikan driver Anda ketika antarmuka perangkat tersedia.

  2. Setelah driver Anda memanggil IWDFDriver::CreateDevice, driver dapat memanggil IWDFDevice2::RegisterRemoteInterfaceNotification untuk setiap antarmuka perangkat yang akan digunakan driver.

Selanjutnya, kerangka kerja memanggil fungsi panggilan balik IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival driver setiap kali antarmuka perangkat tertentu tersedia. Fungsi panggilan balik dapat memanggil IWDFRemoteInterfaceInitialize::GetInterfaceGuid dan IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink untuk menentukan antarmuka perangkat mana yang telah tiba.

Fungsi panggilan balik IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival biasanya harus melakukan hal berikut:

  1. Panggil IWDFDevice2::CreateRemoteInterface untuk membuat objek antarmuka jarak jauh, secara opsional menyediakan antarmuka IRemoteInterfaceCallbackEvent dan IRemoteInterfaceCallbackRemoval .

  2. Panggil IWDFDevice2::CreateRemoteTarget untuk membuat objek target jarak jauh, secara opsional menyediakan antarmuka IRemoteTargetCallbackRemoval .

  3. Panggil IWDFRemoteTarget::OpenRemoteInterface untuk menyambungkan antarmuka perangkat ke target jarak jauh.

    Jika antarmuka perangkat adalah antarmuka yang dibuat enumerator perangkat lunak SWENUM, driver Anda harus memanggil OpenRemoteInterface dari item kerja. (Misalnya, lihat fungsi QueueUserWorkItem di Windows SDK.)

Sekarang driver dapat memformat dan mengirim permintaan I/O ke target I/O jarak jauh.

Selain fungsi panggilan balik IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival , driver berbasis UMDF dapat menyediakan dua fungsi panggilan balik tambahan untuk menerima pemberitahuan peristiwa antarmuka perangkat: