IRP_MN_QUERY_SINGLE_INSTANCE

Artikel
06/15/2023

Semua driver yang mendukung WMI harus menangani IRP ini. Driver dapat menangani RUNP WMI baik dengan memanggil WmiSystemControl atau dengan menangani IRP itu sendiri, seperti yang dijelaskan dalam Menangani Permintaan WMI.

Jika driver memanggil WmiSystemControl untuk menangani permintaan IRP_MN_QUERY_SINGLE_INSTANCE , WMI pada gilirannya memanggil rutinitas DpWmiQueryDataBlock driver tersebut.

Kode Utama

IRP_MJ_SYSTEM_CONTROL

Ketika Dikirim

WMI mengirimkan IRP ini untuk mengkueri satu instans blok data tertentu.

WMI mengirimkan IRP_MN_QUERY_SINGLE_INSTANCE sebelum mengirim IRP_MN_EXECUTE_METHOD. Jika driver mendukung IRP_MN_EXECUTE_METHOD, driver harus memiliki handler IRP_MN_QUERY_SINGLE_INSTANCE untuk blok data yang sama yang metodenya sedang dijalankan.

WMI mengirimkan IRP ini di IRQL = PASSIVE_LEVEL dalam konteks utas arbitrer.

Parameter Input

Parameters.WMI.ProviderId menunjuk ke objek perangkat driver yang harus merespons permintaan. Pointer ini terletak di lokasi tumpukan I/O driver di IRP.

Parameters.WMI.DataPath menunjuk ke GUID yang mengidentifikasi blok data untuk dikueri.

Parameters.WMI.BufferSize menunjukkan ukuran maksimum buffer tidak bertumpuk di Parameters.WMI.Buffer, yang menunjuk ke struktur WNODE_SINGLE_INSTANCE yang mengidentifikasi instans untuk dikueri.

Parameter Output

Jika driver menangani RUNP WMI dengan memanggil WmiSystemControl, WMI mengisi struktur WNODE_SINGLE_INSTANCE dengan data yang disediakan oleh rutinitas DpWmiQueryDataBlock driver.

Jika tidak, driver mengisi struktur WNODE_SINGLE_INSTANCE di Parameters.WMI.Buffer sebagai berikut:

Updates WnodeHeader.BufferSize dengan ukuran, dalam byte, dari struktur WNODE_SINGLE_INSTANCE output, termasuk data instans. Nilai ini harus mencakup panjang nama instans (dilapisi sedemikian rupa sehingga data instans dimulai pada batas kata quad), bahkan jika kelas yang dikueri nama instans statis terdaftar dan penulis driver tidak secara eksplisit menyediakan nama saat melayani IRP ini.
Mengatur SizeDataBlock ke ukuran, dalam byte, dari data instans. Jika nama instans statis sedang digunakan, nilai ini tidak boleh menyertakan ukuran nama instans.
Menulis data instans ke Parameters.WMI.Buffer mulai dari DataBlockOffset. Driver tidak boleh mengubah nilai input DataBlockOffset.

Jika buffer di Parameters.WMI.Buffer terlalu kecil untuk menerima semua data, driver mengisi ukuran yang diperlukan dalam struktur WNODE_TOO_SMALL di Parameters.WMI.Buffer. Jika buffer lebih kecil dari sizeof(WNODE_TOO_SMALL), driver gagal IRP dan mengembalikan STATUS_BUFFER_TOO_SMALL.

Blok Status I/O

Jika driver menangani IRP dengan memanggil WmiSystemControl, WMI menetapkan Irp-IoStatus.Status> dan Irp-IoStatus.Information> di blok status I/O.

Jika tidak, driver mengatur Irp-IoStatus.Status> ke STATUS_SUCCESS atau ke status kesalahan yang sesuai seperti berikut ini:

STATUS_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

Setelah berhasil, driver menetapkan Irp-IoStatus.Information> ke nilai yang dimasukkan ke WnodeHeader.BufferSize. Nilai ini mencakup panjang nama instans statis.

Operasi

Driver dapat menangani RUNP WMI baik dengan memanggil WmiSystemControl atau dengan menangani IRP itu sendiri, seperti yang dijelaskan dalam Menangani Permintaan WMI.

Jika driver menangani RUNP WMI dengan memanggil WmiSystemControl, WmiSystemControl memanggil rutinitas DpWmiQueryDataBlock driver.

Jika driver menangani permintaan IRP_MN_QUERY_SINGLE_INSTANCE itu sendiri, driver harus melakukannya hanya jika Parameters.WMI.ProviderId menunjuk ke objek perangkat yang sama dengan pointer yang diteruskan driver dalam panggilannya ke IoWMIRegistrationControl. Jika tidak, driver harus meneruskan permintaan ke driver bawah berikutnya di tumpukan perangkat.

Sebelum menangani permintaan, driver harus menentukan apakah Parameters.WMI.DataPath menunjuk ke GUID yang didukung driver. Jika tidak, driver harus gagal dalam IRP dan mengembalikan STATUS_WMI_GUID_NOT_FOUND.

Driver bertanggung jawab untuk memvalidasi semua nilai input. Secara khusus, driver harus melakukan hal berikut jika menangani permintaan IRP itu sendiri:

Untuk nama statis, verifikasi bahwa anggota InstanceIndex dari struktur WNODE_SINGLE_INSTANCE berada dalam rentang indeks instans yang didukung oleh driver untuk blok data.
Untuk nama dinamis, verifikasi bahwa string nama instans mengidentifikasi instans blok data yang didukung oleh driver.
Verifikasi bahwa Parameters.WMI.BufferSize menentukan buffer yang cukup besar untuk menerima semua data yang akan dikembalikan driver.

Jika driver mendukung blok data, driver memeriksa WNODE_SINGLE_INSTANCE input di Parameters.WMI.Buffer untuk nama instans, sebagai berikut:

Jika WNODE_FLAG_STATIC_INSTANCE_NAMES diatur dalam WnodeHeader.Flags, driver menggunakan InstanceIndex sebagai indeks ke dalam daftar driver nama instans statis untuk blok tersebut. WMI mendapatkan indeks dari data pendaftaran yang disediakan oleh driver ketika mendaftarkan blok.
Jika WNODE_FLAG_STATIC_INSTANCE_NAMES jelas di WnodeHeader.Flags, driver menggunakan offset di OffsetInstanceName untuk menemukan string nama instans dalam WNODE_SINGLE_INSTANCE input. OffsetInstanceName adalah offset, dalam byte, dari awal struktur ke USHORT, yang merupakan panjang string nama instans dalam byte (bukan karakter), termasuk penghentian null jika ada, diikuti dengan string nama instans di Unicode.

Jika driver tidak dapat menemukan instans yang ditentukan, driver harus gagal IRP dan mengembalikan STATUS_WMI_INSTANCE_NOT_FOUND. Untuk instans dengan nama instans dinamis, status ini menunjukkan bahwa driver tidak mendukung instans. Oleh karena itu, WMI dapat terus mengkueri penyedia data lain, dan mengembalikan kesalahan yang sesuai kepada konsumen data jika penyedia lain menemukan instans tetapi tidak dapat menangani permintaan karena alasan lain.

Jika driver menemukan instans dan dapat menangani permintaan, driver mengisi struktur WNODE_SINGLE_INSTANCE di Parameters.WMI.Buffer dengan data untuk instans.

Jika instans valid tetapi driver tidak dapat menangani permintaan, instans dapat mengembalikan status kesalahan yang sesuai.