IRP_MN_EXECUTE_METHOD
Semua driver yang mendukung metode dalam blok data 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_EXECUTE_METHOD , WMI pada gilirannya memanggil rutinitas DpWmiExecuteMethod driver tersebut.
Kode Utama
Ketika Dikirim
WMI mengirimkan IRP ini untuk menjalankan metode yang terkait dengan blok data.
WMI mengirimkan IRP ini di IRQL = PASSIVE_LEVEL dalam konteks utas arbitrer.
WMI akan mengirim 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.
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 terkait dengan metode yang akan dijalankan.
Parameters.WMI.BufferSize menunjukkan ukuran buffer yang tidak dipagasi di Parameters.WMI.Buffer yang harus >= sizeof(WNODE_METHOD_ITEM) ditambah ukuran data output apa pun untuk metode tersebut.
Parameters.WMI.Buffer menunjuk ke struktur WNODE_METHOD_ITEM di mana MethodID menunjukkan pengidentifikasi metode untuk dijalankan dan DataBlockOffset menunjukkan offset dalam byte dari awal struktur ke byte pertama data input, jika ada. Parameters.WMI.Buffer-> SizeDataBlock menunjukkan ukuran dalam byte input WNODE_METHOD_ITEM termasuk data input, atau nol jika tidak ada input.
Parameter Output
Jika driver menangani RUNP WMI dengan memanggil WmiSystemControl, WMI mengisi WNODE_METHOD_ITEM dengan data yang dikembalikan oleh rutinitas DpWmiExecuteMethod driver.
Jika tidak, driver mengisi struktur WNODE_METHOD_ITEM yang dirujuk Parameters.WMI.Buffer sebagai berikut:
Updates WnodeHeader.BufferSize dengan ukuran output WNODE_METHOD_ITEM, termasuk data output apa pun.
Updates SizeDataBlock dengan ukuran data output, atau nol jika tidak ada data output.
Memeriksa Parameters.WMI.Buffersize untuk menentukan apakah buffer cukup besar untuk menerima output WNODE_METHOD_ITEM termasuk data output apa pun. Jika buffer tidak cukup besar, driver mengisi ukuran yang diperlukan dalam struktur WNODE_TOO_SMALL yang ditunjukkan oleh Parameters.WMI.Buffer. Jika buffer lebih kecil dari sizeof(WNODE_TOO_SMALL), driver gagal IRP dan mengembalikan STATUS_BUFFER_TOO_SMALL.
Menulis data output, jika ada, melalui data input yang dimulai di DataBlockOffset. Driver tidak boleh mengubah nilai input DataBlockOffset.
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
STATUS_WMI_ITEMID_NOT_FOUND
Setelah berhasil, driver menetapkan Irp-IoStatus.Information> ke jumlah byte yang ditulis ke buffer di Parameters.WMI.Buffer.
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, yang rutin memanggil rutinitas DpWmiExecuteMethod driver, atau mengembalikan STATUS_INVALID_DEVICE_REQUEST jika driver tidak menentukan rutinitas.
Jika driver menangani permintaan IRP_MN_EXECUTE_METHOD itu sendiri, itu 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.
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_METHOD_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 MethodId dari struktur WNODE_METHOD_ITEM berada dalam rentang pengidentifikasi metode yang didukung oleh driver untuk blok data, dan bahwa pemanggil diizinkan untuk menjalankan metode.
Verifikasi bahwa anggota DataBlockOffset dan SizeDataBlock dari struktur WNODE_METHOD_ITEM menjelaskan buffer yang cukup besar untuk berisi parameter metode yang ditentukan, dan bahwa parameter valid untuk metode tersebut.
Verifikasi bahwa Parameters.WMI.Buffersize menentukan buffer yang cukup besar untuk menerima struktur WNODE_METHOD_ITEM setelah diperbarui dengan data output.
Jangan berasumsi konteks utas adalah dari aplikasi mode pengguna yang memulai — driver tingkat yang lebih tinggi mungkin telah mengubahnya.
Sebelum menangani permintaan, driver harus menentukan apakah Parameters.WMI.DataPath menunjuk ke GUID yang didukung oleh driver. Jika tidak, driver harus gagal dalam IRP dan mengembalikan STATUS_WMI_GUID_NOT_FOUND.
Jika driver mendukung blok data, driver memeriksa WNODE_METHOD_ITEM 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 input WNODE_METHOD_ITEM. 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.
Driver kemudian memeriksa ID metode dalam input WNODE_METHOD_ITEM untuk menentukan apakah itu metode yang valid untuk blok data tersebut. Jika tidak, driver gagal dalam IRP dan mengembalikan STATUS_WMI_ITEMID_NOT_FOUND.
Jika metode menghasilkan output, driver harus memeriksa ukuran buffer output di Parameters.WMI.BufferSize sebelum melakukan operasi apa pun yang mungkin memiliki efek samping atau yang tidak boleh dilakukan dua kali. Misalnya, jika metode mengembalikan nilai sekelompok penghitung dan kemudian mengatur ulang penghitung, driver harus memeriksa ukuran buffer (dan gagal IRP jika buffer terlalu kecil) sebelum mengatur ulang penghitung. Ini memastikan bahwa WMI dapat mengirim ulang permintaan dengan aman dengan buffer yang lebih besar.
Jika ID instans dan metode valid dan buffer berukuran memadai, driver menjalankan metode . Jika SizeDataBlock dalam input WNODE_METHOD_ITEM bukan nol, driver menggunakan data yang dimulai dari DataBlockOffset sebagai input untuk metode .
Jika metode menghasilkan output, driver menulis data output ke buffer mulai dari DataBlockOffset dan mengatur SizeDataBlock dalam output WNODE_METHOD_ITEM ke jumlah byte data output. Jika metode tidak memiliki data output, driver mengatur SizeDataBlock ke nol. Driver tidak boleh mengubah nilai input DataBlockOffset.
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) |