IRP_MN_CHANGE_SINGLE_INSTANCE
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_CHANGE_SINGLE_INSTANCE , WMI pada gilirannya memanggil rutinitas DpWmiSetDataBlock driver tersebut.
Kode Utama
Ketika Dikirim
WMI mengirimkan IRP ini untuk mengubah semua item data dalam satu instans blok data.
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 ditemukan di lokasi tumpukan I/O driver di IRP.
Parameters.WMI.DataPath menunjuk ke GUID yang mengidentifikasi blok data yang terkait dengan instans yang akan diubah.
Parameters.WMI.BufferSize menunjukkan ukuran buffer yang tidak dipagasi di Parameters.WMI.Buffer.
Parameters.WMI.Buffer menunjuk ke struktur WNODE_SINGLE_INSTANCE yang mengidentifikasi instans dan menentukan nilai data baru.
Parameter Output
Tidak ada.
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_WMI_INSTANCE_NOT_FOUND
STATUS_WMI_GUID_NOT_FOUND
STATUS_WMI_READ_ONLY
STATUS_WMI_SET_FAILURE
Jika berhasil, driver menetapkan Irp-IoStatus.Information> ke nol.
Operasi
Jika driver menangani IRP WMI dengan memanggil WmiSystemControl, yang rutin memanggil rutinitas DpWmiSetDataBlock driver, atau mengembalikan STATUS_WMI_READ_ONLY jika driver tidak menentukan rutinitas.
Jika driver menangani permintaan IRP_MN_CHANGE_SINGLE_INSTANCE itu sendiri, itu melakukannya hanya jika penunjuk objek perangkat di Parameters.WMI.ProviderId cocok dengan pointer yang diteruskan oleh driver dalam panggilannya ke IoWMIRegistrationControl. Jika tidak, driver harus meneruskan permintaan ke driver berikutnya yang lebih rendah.
Jika driver menangani permintaan, driver harus terlebih dahulu memeriksa GUID di Parameters.WMI.DataPath untuk menentukan apakah driver mengidentifikasi blok data yang didukung oleh driver. Jika tidak, driver harus gagal IRP dan mengembalikan STATUS_WMI_GUID_NOT_FOUND.
Jika driver mendukung blok data, driver harus memeriksa struktur WNODE_SINGLE_INSTANCE yang diterima 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 di WNODE_SINGLE_INSTANCE input. OffsetInstanceName adalah offset dalam byte dari awal struktur hingga panjang string nama instans berukuran USHORT dalam byte (bukan karakter), termasuk penghentian null jika ada, diikuti dengan string nama instans di Unicode.
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 anggota DataBlockOffset dan SizeDataBlock dari struktur WNODE_SINGLE_INSTANCE menjelaskan blok data berukuran valid, termasuk padding apa pun yang ada di antara item data, dan bahwa konten buffer valid untuk blok data.
Verifikasi bahwa blok data yang ditentukan adalah blok yang drivernya mengizinkan modifikasi yang dimulai pemanggil. Dengan kata lain, driver tidak boleh mengizinkan modifikasi pada blok data yang Ingin Anda baca-saja.
Jangan berasumsi konteks utas adalah dari aplikasi mode pengguna yang memulai — driver tingkat yang lebih tinggi mungkin telah mengubahnya.
Jika driver tidak dapat menemukan instans yang ditentukan, driver harus gagal IRP dan mengembalikan STATUS_WMI_INSTANCE_NOT_FOUND. Jika instans memiliki 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 mengatur item data yang dapat ditulis dalam instans ke nilai dalam struktur WNODE_SINGLE_INSTANCE , membiarkan item baca-saja tidak berubah. Jika seluruh blok data bersifat baca-saja, driver harus gagal dalam IRP dan mengembalikan STATUS_WMI_READ_ONLY.
Jika instans valid tetapi driver tidak dapat menangani permintaan, instans dapat mengembalikan status kesalahan yang sesuai.
Persyaratan
Header |
Wdm.h (termasuk Wdm.h, Ntddk.h, atau Ntifs.h) |