WMI_QUERY_DATABLOCK_CALLBACK fungsi panggilan balik (wmilib.h)

Artikel
08/08/2023

Rutinitas DpWmiQueryDataBlock mengembalikan satu instans atau semua instans blok data. Rutinitas ini diperlukan.

Sintaks

WMI_QUERY_DATABLOCK_CALLBACK WmiQueryDatablockCallback;

NTSTATUS WmiQueryDatablockCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG InstanceCount,
  [in, out] PULONG InstanceLengthArray,
  [in]      ULONG BufferAvail,
  [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 DpWmiQueryDataBlock dipanggil sebagai respons terhadap permintaan IRP_MN_QUERY_SINGLE_INSTANCE , InstanceIndex menentukan indeks berbasis nol yang menunjukkan instans blok data yang ditentukan untuk dikueri. Jika DpWmiQueryDataBlock dipanggil sebagai respons terhadap permintaan IRP_MN_QUERY_ALL_DATA , InstanceIndex adalah nol.

[in] InstanceCount

Jika DpWmiQueryDataBlock dipanggil sebagai respons terhadap permintaan IRP_MN_QUERY_SINGLE_INSTANCE , InstanceCount adalah 1. Jika DpWmiQueryDataBlock dipanggil sebagai respons terhadap permintaan IRP_MN_QUERY_ALL_DATA , InstanceCount adalah jumlah instans yang akan dikembalikan.

[in, out] InstanceLengthArray

Penunjuk ke array elemen ULONG berukuran InstanceCount yang disediakan penelepon. Driver mengisi setiap elemen array untuk menunjukkan panjang setiap instans yang dikembalikan. Jika BufferAvail adalah nol, InstanceLengthArray adalah NULL.

[in] BufferAvail

Menentukan jumlah maksimum byte yang tersedia untuk menerima data dalam buffer di Buffer. Jika nilai ini nol, pemanggil meminta agar driver menentukan ukuran buffer yang diperlukan dalam panggilannya ke WmiCompleteRequest. Lihat bagian Keterangan untuk informasi selengkapnya.

[out] Buffer

Arahkan ke buffer untuk menerima data instans. Jika buffer cukup besar untuk menerima semua data, driver menulis data instans ke buffer dengan setiap instans yang selaras pada batas 8-byte. Jika buffer terlalu kecil untuk menerima semua data, driver memanggil WmiCompleteRequest dengan BufferUsed diatur ke ukuran yang diperlukan.

Nilai kembali

DpWmiQueryDataBlock mengembalikan STATUS_SUCCESS atau status kesalahan seperti berikut ini:

Jika driver tidak dapat segera menyelesaikan permintaan, driver dapat mengembalikan STATUS_PENDING.

Keterangan

WMI memanggil rutinitas DpWmiQueryDataBlock driver setelah driver memanggil WmiSystemControl sebagai respons terhadap permintaan IRP_MN_QUERY_SINGLE_INSTANCE atau IRP_MN_QUERY_ALL_DATA . Driver harus menempatkan alamat rutinitas DpWmiQueryDataBlock dalam struktur WMILIB_CONTEXT yang diteruskan ke WmiSystemControl.

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 , kueri dapat tiba sebelum penghapusan terjadi.
Verifikasi bahwa nilai InstanceIndex dan InstanceCount , bersama-sama, menentukan sejumlah instans blok data yang berada dalam rentang yang didukung oleh driver untuk blok data. Jika InstanceIndex bukan nol, InstanceCount harus 1. Jika InstanceIndex adalah 0, InstanceCount tidak boleh lebih besar dari jumlah instans yang didukung.
Verifikasi bahwa buffer yang dijelaskan oleh Buffer dan BufferAvail cukup besar untuk menyimpan semua instans yang diminta dari blok data. Setiap instans harus dimulai pada batas 8-byte, dan padding tambahan mungkin ada di antara item data dalam setiap instans.

Setelah menulis data instans ke buffer, driver memanggil WmiCompleteRequest untuk menyelesaikan permintaan. Jika buffer yang dijelaskan oleh Buffer dan BufferAvail adalah nol, atau terlalu kecil untuk menerima semua data yang diminta, panggilan ke WmiCompleteRequest harus menentukan STATUS_BUFFER_TOO_SMALL untuk parameter Status dan ukuran buffer yang diperlukan untuk parameter BufferUsed .

Rutinitas ini dapat dipaginasi.

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