WMI_EXECUTE_METHOD_CALLBACK fungsi panggilan balik (wmilib.h)

Artikel
08/08/2023

Rutinitas DpWmiExecuteMethod menjalankan metode yang terkait dengan blok data. Rutinitas ini bersifat opsional.

Sintaks

WMI_EXECUTE_METHOD_CALLBACK WmiExecuteMethodCallback;

NTSTATUS WmiExecuteMethodCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG MethodId,
  [in]      ULONG InBufferSize,
  [in]      ULONG OutBufferSize,
  [in, out] PUCHAR Buffer
)
{...}

Parameter

[in] DeviceObject

Arahkan ke struktur DEVICE_OBJECT WDM driver.

[in] Irp

Arahkan ke IRP.

[in] GuidIndex

Menentukan blok data dengan memasok indeks berbasis nol ke dalam daftar GUID yang disediakan driver dalam struktur WMILIB_CONTEXT yang diteruskannya ke WmiSystemControl.

[in] InstanceIndex

Jika blok yang ditentukan oleh GuidIndex memiliki beberapa instans, InstanceIndex menentukan nilai indeks berbasis nol yang mengidentifikasi instans.

[in] MethodId

Menentukan ID metode yang akan dijalankan. Driver mendefinisikan ID metode sebagai item dalam blok data.

[in] InBufferSize

Menunjukkan ukuran dalam byte data input. Jika tidak ada data input, InBufferSize adalah nol.

[in] OutBufferSize

Menunjukkan jumlah byte yang tersedia di buffer untuk data output.

[in, out] Buffer

Pointer ke buffer yang menyimpan data input, jika ada, dan menerima data output, jika ada, untuk metode . Jika buffer terlalu kecil untuk menerima semua data output, driver mengembalikan STATUS_BUFFER_TOO_SMALL dan memanggil WmiCompleteRequest dengan ukuran yang diperlukan.

Nilai kembali

DpWmiExecuteMethod mengembalikan STATUS_SUCCESS atau kode kesalahan yang sesuai seperti berikut:

Keterangan

WMI memanggil rutinitas DpWmiExecuteMethod driver setelah driver memanggil WmiSystemControl sebagai respons terhadap permintaan IRP_MN_EXECUTE_METHOD .

Jika driver menerapkan rutinitas DpWmiExecuteMethod , driver harus menempatkan alamat rutin di anggota ExecuteWmiMethod dari struktur WMILIB_CONTEXT yang diteruskannya ke WmiSystemControl. Jika driver tidak menerapkan rutinitas DpWmiExecuteMethod , driver harus mengatur ExecuteWmiMethod ke NULL. Dalam kasus terakhir, WMI mengembalikan STATUS_INVALID_DEVICE_REQUEST ke pemanggil sebagai respons terhadap permintaan IRP_MN_EXECUTE_METHOD apa pun.

Driver bertanggung jawab untuk memvalidasi semua argumen input. Secara khusus, driver harus melakukan hal berikut:

Verifikasi bahwa nilai GuidIndex antara nol dan GuidCount-1, berdasarkan anggota GuidCount dari struktur WMILIB_CONTEXT .
Verifikasi bahwa driver belum menandai blok data yang ditentukan untuk penghapusan. Jika driver baru-baru ini menentukan bendera WMIREG_FLAG_REMOVE_GUID dalam struktur WMIGUIDREGINFO yang terkandung dalam struktur WMILIB_CONTEXT , ada kemungkinan permintaan tambahan tiba sebelum penghapusan terjadi.
Verifikasi bahwa nilai InstanceIndex berada dalam rentang indeks instans yang didukung oleh driver untuk blok data.
Verifikasi bahwa pengidentifikasi metode yang disediakan oleh MethodId adalah pengidentifikasi yang valid untuk blok data yang ditentukan, dan bahwa pemanggil diizinkan untuk menjalankan metode .
Verifikasi bahwa Buffer dan InBufferSize menjelaskan buffer yang cukup besar untuk berisi parameter input metode yang ditentukan, termasuk padding jika perlu, dan verifikasi bahwa parameter input valid.
Verifikasi bahwa Buffer dan OutBufferSize menjelaskan buffer yang cukup besar untuk menerima data output metode yang ditentukan, termasuk padding jika perlu.

Jangan berasumsi konteks utas adalah dari aplikasi mode pengguna yang memulai—driver tingkat yang lebih tinggi mungkin telah mengubahnya.

Jika metode yang ditentukan melakukan operasi yang menyebabkan kehilangan data, seperti mengambil dan mengatur ulang konten sekumpulan penghitung, driver harus memvalidasi ukuran buffer output sebelum melakukan operasi. Dengan begitu, driver dapat kembali STATUS_BUFFER_TOO_SMALL dan memungkinkan penelepon mengirim ulang permintaan dengan buffer yang lebih besar, tanpa mengatur ulang penghitung secara prematur.

Setelah menjalankan metode dan menulis data output apa pun ke buffer, driver memanggil WmiCompleteRequest untuk menyelesaikan permintaan.

Rutinitas ini dapat diperluas.

Untuk informasi selengkapnya tentang menerapkan rutinitas ini, lihat Memanggil WmiSystemControl untuk Menangani IRP WMI.