Struktur WMI WNODE_XXX

WMI menggunakan sekumpulan struktur data standar yang disebut WNODE_XXX untuk meneruskan data antara konsumen data mode pengguna dan penyedia data mode kernel seperti driver. Jika driver menangani permintaan WMI dengan memanggil WmiSystemControl, driver tidak diperlukan untuk membaca atau menulis WNODE_struktur XXX. Jika tidak, driver harus menginterpretasikan input WNODE_ XXX di Parameters.WMI.Buffer dan/atau menulis output WNODE_ XXX ke lokasi tersebut.

Tabel berikut mencantumkan RUN WMI dan struktur WNODE_XXX yang sesuai.

WMI IRP	Struktur WNODE_XXX Terkait
IRP_MN_CHANGE_SINGLE_INSTANCE	WNODE_SINGLE_INSTANCE
IRP_MN_CHANGE_SINGLE_ITEM	WNODE_SINGLE_ITEM
IRP_MN_EXECUTE_METHOD	WNODE_METHOD_ITEM
IRP_MN_QUERY_ALL_DATA	WNODE_ALL_DATA
IRP_MN_QUERY_SINGLE_INSTANCE	WNODE_SINGLE_INSTANCE

Dua struktur WNODE_XXX tambahan, WNODE_EVENT_ITEM dan WNODE_EVENT_REFERENCE, digunakan untuk mengirim pemberitahuan peristiwa yang diaktifkan. Driver yang mendaftarkan blok peristiwa akan, jika peristiwa diaktifkan dan peristiwa terjadi, kirim pemberitahuan peristiwa ke WMI dengan memanggil IoWMIWriteEvent dan melewati struktur WNODE_EVENT_XXX. Untuk informasi tentang mengirim peristiwa WMI, lihat Mengirim Peristiwa WMI.

Setiap struktur WNODE_XXX terdiri dari yang berikut:

• Struktur WNODE_HEADER yang disematkan yang berisi informasi umum untuk semuaXXX WNODE_termasuk ukuran buffer, GUID yang mewakili blok data, dan bendera yang menunjukkan jenis strukturXXX WNODE_, baik menggunakan nama instans statis atau dinamis, dan karakteristik lain dari blok tersebut.

• Anggota tetap dari struktur WNODE_XXX tertentu, seperti offset ke nama dan data instans.

Struktur WNODE_XXX dalam buffer IRP (Parameters.WMI.Buffer) biasanya diikuti oleh data variabel yang terkait dengan permintaan, seperti nama instans dinamis, string nama instans statis, input untuk atau output dari metode, atau data untuk satu atau beberapa instans blok data. Oleh karena itu, ukuran buffer harus melebihi sizeof(WNODE_XXX) dengan jumlah data variabel yang terlibat.

Perhatikan bahwa WMI tidak melakukan pemeriksaan tipe pada data variabel yang disediakan oleh driver. Driver harus menyelaraskan data output pada batas yang sesuai dalam buffer output sehingga konsumen data dapat mengurai data dengan benar. Secara khusus, setiap instans harus dimulai pada batas 8 byte dan setiap itemnya harus diselaraskan pada batas alami sesuai dengan skema blok data yang sebelumnya didaftarkan oleh driver. Nama instans dinamis dapat diselaraskan pada batas 2 byte.

Gambar berikut menunjukkan diagram blok buffer IRP yang berisi struktur WNODE_SINGLE_INSTANCE bahwa driver mungkin kembali sebagai respons terhadap permintaan IRP_MN_QUERY_SINGLE_INSTANCE.

Mulai dari bagian atas gambar sebelumnya:

• Struktur WNODE_HEADER di awal WNODE_SINGLE_INSTANCE terkandung dalam anggota WnodeHeader. WMI mengisi semua anggota WNODE_HEADER sebelum mengirim permintaan. Dalam WNODE_HEADER:

  • WnodeHeader.Buffersize menunjukkan ukuran WNODE_SINGLE_INSTANCE, termasuk data yang mengikuti anggota tetap struktur. (Nilai WnodeHeader.Buffersize biasanya kurang dari Parameters.WMI.Buffersize, yang menunjukkan ukuran buffer yang dialokasikan oleh WMI untuk menerima output dari driver.)
  • WnodeHeader.Guid berisi GUID yang mengidentifikasi blok data.
  • Dalam contoh ini, WnodeHeader.Flags menunjukkan bahwa struktur ini adalah WNODE_SINGLE_INSTANCE dan bahwa blok data menggunakan nama instans statis.

• Karena blok data menggunakan nama instans statis, WMI menetapkan InstanceIndex ke indeks instans dalam daftar nama instans statis yang diteruskan oleh driver saat mendaftarkan blok. offsetInstanceNames tidak digunakan.

• WMI mengatur DataBlockOffset untuk menunjukkan offset dari awal buffer ke byte pertama data instans. (Pengandar tidak boleh mengubah nilai ini) Sekali lagi karena blok data menggunakan nama instans statis, offset ini menunjukkan lokasi yang sama dengan VariableData. Jika blok data menggunakan nama instans dinamis, nama instans akan dimulai pada VariableData dan DataBlockOffset akan menentukan offset yang lebih besar ke dalam buffer.

• Driver mengatur SizeDataBlock ke jumlah byte data instans yang dikembalikan.

• Pada VariableData (setelah data nama instans, jika ada), driver menulis data instans untuk instans yang diminta di buffer output.

Driver membaca dan menulis struktur WNODE_METHOD_ITEM dan WNODE_SINGLE_ITEM dengan cara yang sama seperti WNODE_SINGLE_INSTANCE. Struktur ini menyerupai satu sama lain di mana masing-masing memiliki anggota tetap OffsetInstanceName, InstanceIndex, DataBlockOffset, SizeDataBlock (atau, dalam kasus WNODE_SINGLE_ITEM, SizeDataItem) dan VariableData. WNODE_METHOD_ITEM menyertakan MethodId dan WNODE_SINGLE_ITEM menyertakan ItemId yang WNODE_SINGLE_INSTANCE kurang.

WNODE_ALL_DATA berbeda dari struktur sebelumnya karena digunakan untuk meneruskan beberapa instans blok data, mungkin termasuk nama instans dinamis dan mungkin dengan ukuran yang berbeda.

Gambar berikut menunjukkan diagram blok buffer IRP yang berisi WNODE_ALL_DATA bahwa driver mungkin kembali sebagai respons terhadap permintaan IRP_MN_QUERY_ALL_DATA.

Mulai dari bagian atas gambar sebelumnya:

• Seperti yang dijelaskan pada gambar sebelumnya, struktur WNODE_HEADER di awal WNODE_ALL_DATA terkandung dalam anggota WnodeHeader. WnodeHeader.Buffersize dan WnodeHeader.Guid menunjukkan ukuran WNODE_ALL_DATA dan GUID blok data.

  Dalam contoh ini, WMI menetapkan WnodeHeader.Flags untuk menunjukkan bahwa struktur ini adalah WNODE_ALL_DATA dan bahwa blok data terdaftar dengan nama instans dinamis (yaitu, WMI menghapus WNODE_FLAG_STATIC_INSTANCE_NAMES dan WNODE_FLAG_PDO_INSTANCE_NAMES). Pada output, driver mengatur WNODE_FLAG_FIXED_INSTANCE_SIZE untuk menunjukkan bahwa semua instans berukuran sama.

• WMI mengatur DataBlockOffset untuk menunjukkan offset dari awal buffer ke byte pertama data instans. (Pengandar tidak boleh mengubah nilai ini). Dalam contoh ini, data instans mengikuti nama instans di OffsetInstanceNameOffsets.

• Driver mengatur InstanceCount untuk menunjukkan jumlah instans yang dikembalikan.

• WNODE_XXX untuk blok data yang menggunakan nama instans dinamis selalu berisi string nama instans. Karena contoh ini menggunakan nama instans dinamis, OffsetInstanceNameOffsets menunjukkan offset dari awal buffer ke array offset ke nama instans dinamis di buffer.

• FixedInstanceSize menunjukkan jumlah byte data dalam setiap instans yang dikembalikan oleh driver. Jika instans blok data ini bervariasi ukurannya, driver akan menghapus WNODE_FLAG_FIXED_INSTANCE_SIZE di WnodeHeader.Flags dan mengatur OffsetInstanceDataAndLength ke array struktur OFFSETINSTANCEDATAANDLENGTH, masing-masing menentukan offset ke data untuk satu instans dan jumlah byte dalam instans tersebut alih-alih mengatur FixedInstanceSize.

Untuk informasi selengkapnya tentang struktur WNODE_XXX, lihat Struktur Sistem.