WMI_FUNCTION_CONTROL_CALLBACK fungsi panggilan balik (wmilib.h)

Artikel
08/08/2023

Rutinitas DpWmiFunctionControl memungkinkan atau menonaktifkan pemberitahuan peristiwa, dan mengaktifkan atau menonaktifkan pengumpulan data untuk blok data yang didaftarkan driver mahal untuk dikumpulkan. Rutinitas ini bersifat opsional.

Sintaks

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

NTSTATUS WmiFunctionControlCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] WMIENABLEDISABLECONTROL Function,
  [in] BOOLEAN Enable
)
{...}

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] Function

Menentukan apa yang harus diaktifkan atau dinonaktifkan. WmiEventControl menunjukkan peristiwa, dan WmiDataBlockControl menunjukkan pengumpulan data untuk blok yang terdaftar mahal untuk dikumpulkan (yaitu, blok yang ditetapkan driver WMIREG_FLAG_EXPENSIVE dalam Bendera struktur WMIGUIDREGINFO yang digunakan untuk mendaftarkan blok).

[in] Enable

Menentukan TRUE untuk mengaktifkan peristiwa atau pengumpulan data, atau FALSE untuk menonaktifkannya.

Nilai kembali

DpWmiFunctionControl mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai seperti:

Keterangan

WMI memanggil rutinitas DpWmiFunctionControl driver setelah driver memanggil WmiSystemControl sebagai respons terhadap salah satu permintaan berikut:

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

Jika driver menerapkan rutinitas DpWmiFunctionControl , driver harus menempatkan alamat rutin di anggota WmiFunctionControl dari struktur WMILIB_CONTEXT yang diteruskannya ke WmiSystemControl. Jika driver tidak menerapkan rutinitas DpWmiFunctionControl , driver harus mengatur WmiFunctionControl ke NULL. Dalam kasus terakhir, WMI mengembalikan STATUS_SUCCESS ke pemanggil.

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

Verifikasi bahwa nilai GuidIndex berada di 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.

Tidak perlu bagi driver untuk memeriksa apakah peristiwa atau pengumpulan data sudah diaktifkan untuk blok, karena WMI mengirim satu permintaan pengaktifan ketika konsumen data pertama mengaktifkan blok, dan mengirim satu permintaan penonaktifan ketika konsumen data terakhir menonaktifkan blok. WMI tidak akan memanggil DpWmiFunctionControl untuk mengaktifkan blok tanpa panggilan intervensi untuk menonaktifkannya.

Setelah mengaktifkan atau menonaktifkan peristiwa atau pengumpulan data untuk blok tersebut, driver memanggil WmiCompleteRequest untuk menyelesaikan permintaan.

Rutinitas ini dapat dipaginasi.

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