IRP_MN_QUERY_INTERFACE
Permintaan IRP_MN_QUERY_INTERFACE memungkinkan driver untuk mengekspor antarmuka panggilan langsung ke driver lain.
Driver bus yang mengekspor antarmuka harus menangani permintaan ini untuk perangkat anaknya (PDO anak). Fungsi dan filter dapat secara opsional menangani permintaan ini.
"Antarmuka" dalam konteks ini terdiri dari satu atau beberapa rutinitas, dan mungkin data, yang diekspor oleh driver atau sekumpulan driver. Antarmuka memiliki struktur yang menjelaskan isinya dan GUID yang mengidentifikasi jenisnya.
Misalnya, driver bus PCMCIA mengekspor antarmuka jenis GUID_PCMCIA_INTERFACE_STANDARD yang berisi rutinitas untuk operasi seperti mendapatkan kondisi perlindungan tulis dari kartu memori PCMCIA. Driver fungsi untuk kartu memori seperti itu dapat mengirim permintaan IRP_MN_QUERY_INTERFACE ke driver bus PCMCIA induk untuk mendapatkan pointer ke rutinitas antarmuka PCMCIA.
Catatan
Saat memperkenalkan versi baru antarmuka yang ada, buat GUID baru alih-alih merevisi bidang Ukuran atau Versi dari struktur ANTARMUKA . Untuk informasi selengkapnya, lihat Menggunakan Antarmuka Driver-Defined.
Bagian ini menjelaskan IRP antarmuka kueri sebagai mekanisme umum. Driver yang mengekspos antarmuka harus memberikan informasi tambahan tentang antarmuka spesifiknya.
Nilai
0x08
Kode Utama
Ketika Dikirim
Driver atau komponen sistem mengirimkan IRP ini untuk mendapatkan informasi tentang antarmuka yang diekspor oleh driver untuk perangkat.
Komponen driver atau sistem mengirimkan IRP ini di IRQL = PASSIVE_LEVEL dalam konteks utas arbitrer.
Driver dapat menerima IRP ini kapan saja setelah rutinitas AddDevice driver dipanggil untuk perangkat. Perangkat mungkin atau mungkin tidak dimulai ketika IRP ini dikirim (artinya, Anda tidak dapat berasumsi bahwa driver telah berhasil menyelesaikan permintaan IRP_MN_START_DEVICE untuk perangkat).
Parameter Input
Anggota Parameters.QueryInterface dari struktur IO_STACK_LOCATION itu sendiri adalah struktur, yang menjelaskan antarmuka yang diminta. Struktur berisi informasi berikut:
CONST GUID *InterfaceType;
USHORT Size;
USHORT Version;
PINTERFACE Interface;
PVOID InterfaceSpecificData
Anggota struktur didefinisikan sebagai berikut:
InterfaceType
Menunjuk ke GUID yang mengidentifikasi antarmuka yang diminta. GUID dapat untuk antarmuka yang ditentukan sistem, seperti GUID_BUS_INTERFACE_STANDARD, atau antarmuka kustom. GUID untuk antarmuka yang ditentukan sistem tercantum dalam Wdmguid.h. GUID untuk antarmuka kustom harus dihasilkan dengan Uuidgen.
Ukuran
Menentukan ukuran antarmuka yang diminta. Driver yang menangani IRP ini tidak boleh mengembalikan struktur INTERFACE yang lebih besar dari byte Ukuran .
Version
Menentukan versi antarmuka yang diminta.
Jika driver mendukung lebih dari satu versi antarmuka, driver mengembalikan versi terdekat yang didukung tanpa melebihi versi yang diminta. Komponen yang mengirim IRP harus memeriksa bidang Interface.Version yang dikembalikan dan menentukan apa yang harus dilakukan berdasarkan nilai tersebut.
Interface
Menunjuk ke struktur untuk mengembalikan antarmuka yang diminta. Struktur ini harus berisi struktur INTERFACE sebagai anggota pertamanya. Komponen yang mengirim IRP mengalokasikan struktur ini dari memori halaman.
Driver yang mengekspor antarmuka mendefinisikan jenis struktur baru yang berisi struktur INTERFACE , ditambah anggota untuk rutinitas dan/atau data di antarmuka. (Driver juga mendefinisikan GUID untuk antarmuka, seperti yang dijelaskan dalam anggota InterfaceType , di atas.)
Driver yang mengekspor antarmuka menentukan lingkungan eksekusi untuk setiap rutinitas dalam antarmuka, termasuk IRQL di mana rutinitas dapat dipanggil, dan sebagainya.
InterfaceSpecificData
Menentukan informasi tambahan tentang antarmuka yang diminta.
Untuk beberapa antarmuka, komponen yang mengirim IRP menentukan informasi tambahan di bidang ini. Biasanya, bidang ini adalah NULL dan InterfaceType dan Version cukup untuk mengidentifikasi antarmuka yang diminta.
Parameter Output
Setelah berhasil, driver mengisi anggota struktur Parameters.QueryInterface.Interface .
Blok Status I/O
Driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau ke status kesalahan yang sesuai.
Setelah berhasil, pengemudi bus menetapkan Irp-IoStatus.Information> ke nol.
Jika fungsi atau driver filter tidak menangani IRP ini, ia memanggil IoSkipCurrentIrpStackLocation dan meneruskan IRP ke driver berikutnya. Driver seperti itu tidak boleh memodifikasi Irp-IoStatus.Status> dan tidak boleh menyelesaikan IRP.
Jika driver bus tidak mengekspor antarmuka yang diminta dan oleh karena itu tidak menangani IRP ini untuk PDO anak, driver bus meninggalkan Irp-IoStatus.Status> apa adanya dan menyelesaikan IRP.
Operasi
Driver menangani IRP ini jika parameter menentukan antarmuka yang didukung driver.
Driver tidak boleh mengantre IRP ini jika IRP meminta antarmuka yang tidak didukung driver. Driver harus memeriksa Parameters.QueryInterface.InterfaceType dalam struktur IO_STACK_LOCATION . Jika antarmuka bukan salah satu yang didukung driver, driver harus meneruskan IRP ke driver bawah berikutnya di tumpukan perangkat tanpa memblokir.
Setiap antarmuka harus menyediakan rutinitas InterfaceReference dan InterfaceDereference , dan driver yang mengekspor antarmuka harus menyediakan alamat rutinitas ini dalam struktur ANTARMUKA . Sebelum driver mengembalikan antarmuka sebagai respons terhadap IRP, driver harus meningkatkan jumlah referensi antarmuka dengan memanggil rutinitas InterfaceReference-nya . Ketika driver yang meminta antarmuka selesai menggunakannya, driver tersebut harus mengurangi jumlah referensi dengan memanggil rutinitas InterfaceDereference antarmuka.
Jika driver yang mengirim IRP (driver x) nanti meneruskan antarmuka ke driver lain (driver y) maka driver x harus menaikkan jumlah referensi antarmuka dan driver y harus menguranginya.
Driver yang menangani IRP ini harus menghindari meneruskan IRP ke tumpukan perangkat lain untuk mendapatkan antarmuka yang diminta. Desain seperti itu akan menciptakan dependensi antara tumpukan perangkat yang sulit dikelola. Misalnya, perangkat yang diwakili oleh tumpukan perangkat kedua tidak dapat dihapus sampai driver yang sesuai dalam dereferensi tumpukan pertama antarmuka.
Antarmuka dapat spesifik bus atau bus independen. Antarmuka khusus bus didefinisikan dalam file header untuk bus tersebut. Sistem mendefinisikan antarmuka independen bus, BUS_INTERFACE_STANDARD, untuk mengekspor antarmuka bus standar.
Lihat Plug and Play aturan umum untuk menangani Plug and Play runtime integrasi kecil.
IRP ini digunakan secara khusus untuk melewati titik masuk rutin antara driver mode kernel berlapis untuk perangkat. Jangan membingungkan antarmuka yang diekspos oleh IRP ini dengan antarmuka perangkat. Antarmuka perangkat digunakan terutama untuk mengekspos jalur ke perangkat untuk digunakan oleh komponen mode pengguna atau komponen kernel lainnya. Untuk informasi selengkapnya tentang antarmuka perangkat, lihat Kelas Antarmuka Perangkat.
Mengirim IRP ini
Lihat Menangani IRP untuk informasi tentang pengiriman RUNPS. Langkah-langkah berikut berlaku khusus untuk IRP ini:
Alokasikan struktur INTERFACE dari kumpulan halaman dan inisialisasi ke nol. Jika antarmuka akan dipanggil di IRQL >= DISPATCH_LEVEL, berdasarkan kontrak antarmuka, pemanggil dapat menyalin konten ke memori yang dialokasikan dari kumpulan yang tidak disebarkan.
Atur nilai di lokasi tumpukan I/O berikutnya dari IRP: atur MajorFunction ke IRP_MJ_PNP, atur MinorFunction ke IRP_MN_QUERY_INTERFACE, dan atur nilai yang sesuai di Parameters.QueryInterface.
Inisialisasi IoStatus.Status ke STATUS_NOT_SUPPORTED.
Batalkan alokasi IRP dan struktur INTERFACE ketika tidak lagi diperlukan.
Gunakan rutinitas antarmuka dan parameter konteks seperti yang dijelaskan dalam spesifikasi untuk antarmuka.
Turunkan jumlah referensi menggunakan rutinitas InterfaceDereference saat antarmuka tidak lagi diperlukan. Jangan panggil rutinitas antarmuka apa pun setelah dereferensi antarmuka.
Driver biasanya mengirim IRP ini ke bagian atas tumpukan perangkat tempat driver terpasang. Jika driver mengirim IRP ini ke tumpukan perangkat yang berbeda, driver harus mendaftar untuk pemberitahuan perangkat target pada perangkat lain jika perangkat lain bukan leluhur perangkat yang dilayvis driver. Driver seperti itu memanggil IoRegisterPlugPlayNotification dengan EventCategory dari EventCategoryTargetDeviceChange. Ketika driver menerima pemberitahuan jenis GUID_TARGET_DEVICE_QUERY_REMOVE, driver harus mendereferensikan antarmuka. Driver dapat meminta kembali antarmuka jika menerima pemberitahuan GUID_TARGET_DEVICE_REMOVE_CANCELLED berikutnya.
Persyaratan
Header |
Wdm.h (termasuk Wdm.h, Ntddk.h, atau Ntifs.h) |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk