IRP_MN_CHANGE_SINGLE_ITEM
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_ITEM , WMI pada gilirannya memanggil rutinitas DpWmiSetDataItem driver tersebut.
Kode Utama
Ketika Dikirim
WMI mengirimkan IRP ini untuk mengubah satu 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 terletak di lokasi tumpukan I/O driver di IRP.
Parameters.WMI.DataPath menunjuk ke GUID yang mengidentifikasi blok data yang akan diatur.
Parameters.WMI.BufferSize menunjukkan ukuran buffer yang tidak dipagasi di Parameters.WMI.Buffer.
Parameters.WMI.Buffer, menunjuk ke struktur WNODE_SINGLE_ITEM yang mengidentifikasi instans blok data, ID item yang akan diatur, dan 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_ITEMID_NOT_FOUND
STATUS_WMI_GUID_NOT_FOUND
STATUS_WMI_READ_ONLY
STATUS_WMI_SET_FAILURE
Setelah berhasil, driver menetapkan Irp-IoStatus.Information> ke nol.
Operasi
Jika driver menangani runtime integrasi WMI dengan memanggil WmiSystemControl, yang rutin memanggil rutinitas DpWmiSetDataItem driver, atau mengembalikan STATUS_WMI_READ_ONLY jika driver tidak menentukan rutinitas.
Jika driver menangani permintaan IRP_MN_CHANGE_SINGLE_ITEM itu sendiri, driver harus melakukannya hanya jika Parameters.WMI.ProviderId menunjuk ke objek perangkat yang sama dengan pointer yang diteruskan driver ke IoWMIRegistrationControl. Jika tidak, driver harus meneruskan permintaan ke driver berikutnya yang lebih rendah.
Jangan terapkan dukungan untuk IRP_MN_CHANGE_SINGLE_ITEM kecuali Anda yakin bahwa komponen mode pengguna yang disediakan sistem memerlukan kemampuan ini.
Sebelum menangani permintaan, driver harus menentukan apakah Parameters.WMI.DataPath menunjuk ke GUID yang didukung 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_ITEM input yang dirujuk 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 struktur WNODE_SINGLE_ITEM input. OffsetInstanceName adalah offset dalam byte dari awal struktur hingga panjang string nama instans berukuran USHORT dalam byte (bukan karakter). Panjang ini mencakup terminator 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_ITEM 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 ItemId dari struktur WNODE_SINGLE_ITEM berada dalam rentang pengidentifikasi item yang didukung oleh driver untuk blok data.
Verifikasi bahwa anggota DataBlockOffset dan SizeDataItem dari struktur WNODE_SINGLE_ITEM menjelaskan blok data berukuran valid, dan bahwa konten buffer valid untuk item data.
Verifikasi bahwa item data yang ditentukan adalah item yang memungkinkan modifikasi yang dimulai oleh driver pemanggil. Dengan kata lain, driver tidak boleh mengizinkan modifikasi pada item data yang Anda maksudkan sebagai 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. 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 mengatur item data dalam instans ke nilai dalam WNODE_SINGLE_ITEM. Jika item data bersifat baca-saja, driver membiarkan item tidak berubah, gagal 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) |