struktur WNODE_HEADER (wmistr.h)

Artikel
08/08/2023

Struktur WNODE_HEADER adalah anggota pertama dari semua struktur WNODE_XXX lainnya . Ini berisi informasi yang umum untuk semua struktur tersebut.

Sintaks

typedef struct _WNODE_HEADER {
  ULONG BufferSize;
  ULONG ProviderId;
  union {
    ULONG64 HistoricalContext;
    struct {
      ULONG Version;
      ULONG Linkage;
    } DUMMYSTRUCTNAME;
  } DUMMYUNIONNAME;
  union {
    ULONG         CountLost;
    HANDLE        KernelHandle;
    LARGE_INTEGER TimeStamp;
  } DUMMYUNIONNAME2;
  GUID  Guid;
  ULONG ClientContext;
  ULONG Flags;
} WNODE_HEADER, *PWNODE_HEADER;

Anggota

BufferSize

Anggota ini menentukan ukuran, dalam byte, dari buffer yang tidak disebarkan untuk menerima data WNODE_XXX yang akan dikembalikan, termasuk struktur WNODE_HEADER ini, anggota tambahan dari struktur WNODE_XXX dari jenis yang ditunjukkan oleh Bendera, dan data yang ditentukan WMI atau driver yang menyertai struktur tersebut.

ProviderId

Jika Bendera diatur ke WNODE_FLAG_EVENT_ITEM atau WNODE_FLAG_EVENT_REFERENCE, ProviderId harus berisi ID penyedia WMI yang terkait dengan objek perangkat. Anda dapat memperoleh nilai ProviderId dengan memanggil IoWMIDeviceObjectToProviderId. Jika Bendera diatur ke nilai lain, anggota ini akan dicadangkan.

DUMMYUNIONNAME

DUMMYUNIONNAME.HistoricalContext

Anggota ini menyimpan handel ke sesi pelacakan peristiwa.

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Version

Anggota ini dicadangkan untuk WMI.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Linkage

Anggota ini dicadangkan untuk WMI.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.CountLost

Dicadangkan

DUMMYUNIONNAME2.KernelHandle

Anggota ini dicadangkan untuk WMI.

DUMMYUNIONNAME2.TimeStamp

Anggota ini menunjukkan waktu saat driver mengumpulkan data WNODE_XXX . Nilai waktu ini dinyatakan dalam format waktu sistem absolut. Waktu sistem absolut adalah jumlah interval 100-nanodetik sejak awal tahun 1601 di kalender Gregorian. Driver dapat memanggil KeQuerySystemTime untuk mendapatkan nilai ini. Jika blok ditulis ke file log (WNODE_FLAG_LOG_WNODE), driver NT mungkin juga mengatur WNODE_FLAG_USE_TIMESTAMP di Bendera untuk meminta pencatat sistem membiarkan nilai Tanda Waktu tidak berubah.

Guid

Anggota ini menunjukkan GUID yang mewakili blok data yang terkait dengan WNODE_XXX yang akan dikembalikan.

ClientContext

Anggota ini menyimpan jenis jam untuk sesi tersebut. Nilai yang mungkin disertakan dalam tabel berikut.

Nilai	Deskripsi
1	Nilai penghitung kinerja (juga disebut QPC, QueryPerformanceCounter, atau PerfCounter)
2	Timer sistem
3	Siklus CPU

Flags

Anggota ini menunjukkan jenis struktur WNODE_XXX yang berisi struktur WNODE_HEADER:

WNODE_FLAG_ALL_DATA

Sisa struktur WNODE_ALL_DATA mengikuti struktur WNODE_HEADER di buffer.

WMI menetapkan bendera ini dalam struktur WNODE_HEADER yang diteruskannya dengan permintaan IRP_MN_QUERY_ALL_DATA .

Driver menetapkan bendera ini dalam struktur WNODE_HEADER peristiwa yang terdiri dari semua instans blok data. Jika ukuran blok data identik untuk semua instans, driver juga mengatur WNODE_FLAG_FIXED_INSTANCE_SIZE.

WNODE_FLAG_EVENT_ITEM

Driver mengatur bendera ini untuk menunjukkan bahwa struktur WNODE_XXX dihasilkan sebagai peristiwa. Bendera ini hanya valid jika WNODE_FLAG_ALL_DATA, WNODE_FLAG_SINGLE_INSTANCE, atau WNODE_FLAG_SINGLE_ITEM juga diatur.

WNODE_FLAG_EVENT_REFERENCE

Sisa struktur WNODE_EVENT_REFERENCE mengikuti struktur WNODE_HEADER di buffer.

Driver mengatur bendera ini saat menghasilkan peristiwa yang lebih besar dari ukuran maksimum yang ditentukan dalam registri untuk suatu peristiwa. WMI menggunakan informasi dalam struktur WNODE_EVENT_REFERENCE untuk meminta data peristiwa dan menjadwalkan permintaan tersebut sesuai dengan nilai WNODE_FLAG_SEVERITY_MASK.

WNODE_FLAG_METHOD_ITEM

Sisa struktur WNODE_METHOD_ITEM mengikuti struktur WNODE_HEADER di buffer.

WMI menetapkan bendera ini dalam struktur WNODE_HEADER yang diteruskannya dengan permintaan IRP_MN_EXECUTE_METHOD .

WNODE_FLAG_SINGLE_INSTANCE

Sisa struktur WNODE_SINGLE_INSTANCE mengikuti struktur WNODE_HEADER di buffer.

WMI mengatur bendera ini dalam struktur WNODE_HEADER yang diteruskannya dengan permintaan untuk mengkueri atau mengubah instans.

Driver menetapkan bendera ini dalam struktur WNODE_HEADER peristiwa yang terdiri dari satu instans blok data.

WNODE_FLAG_SINGLE_ITEM

Sisa struktur WNODE_SINGLE_INSTANCE mengikuti struktur WNODE_HEADER di buffer.

WMI mengatur bendera ini dalam struktur WNODE_HEADER yang diteruskannya dengan permintaan untuk mengubah item.

Driver mengatur bendera ini dalam struktur WNODE_HEADER peristiwa yang terdiri dari satu item data.

WNODE_FLAG_TOO_SMALL

Sisa struktur WNODE_TOO_SMALL mengikuti struktur WNODE_HEADER dalam buffer.

Driver mengatur bendera ini ketika melewati struktur WNODE_TOO_SMALL , menunjukkan bahwa buffer terlalu kecil untuk semua data WNODE_XXX yang akan dikembalikan.

Selain itu, Bendera mungkin diatur dengan satu atau beberapa bendera berikut yang memberikan informasi tambahan tentang WNODE_XXX:

WNODE_FLAG_FIXED_INSTANCE_SIZE

Semua instans blok data berukuran sama. Bendera ini hanya valid jika WNODE_FLAG_ALL_DATA juga diatur.

WNODE_FLAG_INSTANCES_SAME

Jumlah instans dan nama instans dinamis dalam struktur WNODE_ALL_DATA yang akan dikembalikan identik dengan instans yang dikembalikan dari kueri WNODE_ALL_DATA sebelumnya. Bendera ini hanya valid jika WNODE_FLAG_ALL_DATA juga diatur. Bendera ini diabaikan untuk blok data yang terdaftar dengan nama instans statis.

Untuk performa yang dioptimalkan, driver harus mengatur bendera ini jika dapat melacak perubahan pada jumlah atau nama blok datanya. WMI kemudian dapat melewati pemrosesan yang diperlukan untuk mendeteksi dan memperbarui nama instans dinamis.

WNODE_FLAG_STATIC_INSTANCE_NAMES

Data WNODE_XXX yang akan dikembalikan tidak menyertakan nama instans.

WMI mengatur bendera ini sebelum meminta data WNODE_XXX untuk blok data yang terdaftar dengan nama instans statis. Setelah menerima WNODE_XXXX yang dikembalikan dari driver, WMI mengisi nama instans statis yang ditentukan saat pendaftaran sebelum meneruskan WNODE_XXXX yang dikembalikan ke konsumen data.

WNODE_FLAG_PDO_INSTANCE_NAMES

Nama instans statis didasarkan pada ID instans perangkat PDO untuk perangkat. Driver meminta nama tersebut dengan mengatur WMIREG_FLAG_INSTANCE_PDO di WMIREGGUID yang digunakannya untuk mendaftarkan blok.

WMI mengatur bendera ini sebelum meminta data WNODE_XXX untuk blok data yang terdaftar dengan nama instans berbasis PDO.

WNODE_FLAG_SEVERITY_MASK

Tingkat keparahan peristiwa yang ditentukan pengemudi yang terkait dengan WNODE_EVENT_REFERENCE yang dikembalikan, dengan 0x00 menunjukkan tingkat keparahan yang paling tidak parah dan 0xff menunjukkan tingkat yang paling parah.

WMI menggunakan nilai bendera ini untuk memprioritaskan permintaannya untuk data peristiwa.

WNODE_FLAG_USE_TIMESTAMP

Pencatat sistem tidak boleh mengubah nilai TimeStamp yang ditetapkan oleh driver.

Driver NT mungkin juga mengatur Bendera ke satu atau beberapa nilai berikut agar blok peristiwa ditulis ke file log sistem:

WNODE_FLAG_LOG_WNODE

Blok kejadian akan dikirim ke pencatat sistem. Header peristiwa adalah struktur WNODE_HEADER standar. Jika driver menghapus WNODE_FLAG_TRACED_GUID, blok juga akan dikirim ke WMI untuk pengiriman ke konsumen data apa pun yang telah mengaktifkan peristiwa tersebut. Driver harus mengalokasikan WNODE_XXX dari memori kumpulan. WMI membebaskan memori setelah mengirimkan peristiwa kepada konsumen data.

WNODE_FLAG_TRACED_GUID

Blok kejadian hanya akan dikirim ke pencatat sistem. Ini tidak dikirim ke konsumen data WMI. Header peristiwa adalah struktur EVENT_TRACE_HEADER , dideklarasikan dalam Evntrace.h, bukan WNODE_HEADER. Driver harus mengalokasikan memori untuk WNODE_XXX dan membebaskannya setelah IoWMIWriteEvent kembali. Driver dapat mengalokasikan memori tersebut baik dari tumpukan atau, untuk meminimalkan overhead mengalokasikan dan membebaskan memori, dari penyimpanan lokal utas driver jika driver membuat dan memelihara kumpulan utasnya sendiri.

WNODE_FLAG_USE_GUID_PTR

Anggota Guid menunjuk ke GUID dalam memori, daripada berisi GUID itu sendiri. Pencatat sistem mendereferensikan pointer sebelum meneruskan data ke konsumen. Bendera ini hanya valid jika WNODE_FLAG_LOG_WNODE atau WNODE_FLAG_TRACED_GUID juga diatur.

WNODE_FLAG_USE_MOF_PTR

Data yang mengikuti anggota tetap struktur WNODE_XXX terdiri dari array struktur MOF_FIELD, yang ditentukan dalam Evntrace.h, yang berisi pointer ke data dan ukuran daripada data itu sendiri. Array dapat berisi hingga elemen MAX_MOF_FIELD. Pencatat sistem mendereferensikan pointer sebelum meneruskan data ke konsumen Bendera ini hanya berlaku untuk blok yang terdaftar di WMIREG_FLAG_TRACED_GUID.

Keterangan

Dalam permintaan IRP_MN_CHANGE_XXX atau IRP_MN_EXECUTE_METHOD , BufferSize dalam IRP menunjukkan ukuran maksimum dalam byte buffer output, sementara BufferSize dalam input WNODE_HEADER untuk permintaan tersebut menunjukkan ukuran, dalam byte, dari data input dalam buffer.