WNODE_HEADER結構 (wmistr.h)

發行項
03/05/2024

WNODE_HEADER 結構是所有其他WNODE_XXX 結構的第一個成員。它包含所有這類結構通用的資訊。

語法

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;

成員

BufferSize

這個成員會指定要傳回之非分頁緩衝區的大小，以位元組為單位接收要傳回的任何WNODE_XXX數據，包括這個WNODE_HEADER結構、Flags 所指示之類型之 WNODE_XXX 結構的其他成員，以及任何隨附該結構的 WMI 或驅動程式判斷數據。

ProviderId

如果 Flags 設定為 WNODE_FLAG_EVENT_ITEM 或 WNODE_FLAG_EVENT_REFERENCE，ProviderId 應該包含與裝置對象相關聯的 WMI 提供者識別碼。您可以呼叫 IoWMIDeviceObjectToProviderId 來取得 ProviderId 值。如果 Flags 設定為任何其他值，則會保留此成員。

DUMMYUNIONNAME

DUMMYUNIONNAME.HistoricalContext

此成員會將句柄儲存至事件追蹤會話。

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Version

此成員保留給 WMI。

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Linkage

此成員保留給 WMI。

DUMMYUNIONNAME2

DUMMYUNIONNAME2.CountLost

保留

DUMMYUNIONNAME2.KernelHandle

此成員保留給 WMI。

DUMMYUNIONNAME2.TimeStamp

這個成員表示驅動程式收集 WNODE_XXX 數據的時間。這個時間值是以絕對系統時間格式表示。絕對系統時間是從公曆 1601 年開始起的 100 奈秒間隔數目。驅動程式可以呼叫 KeQuerySystemTime 來取得此值。如果要將區塊寫入記錄檔 (WNODE_FLAG_LOG_WNODE) ，NT 驅動程式也可能在 Flags 中設定WNODE_FLAG_USE_TIMESTAMP，要求系統記錄器保留 TimeStamp 的值不變。

Guid

這個成員表示 GUID，表示與要傳回 之 WNODE_XXX 相關聯的數據區塊。

ClientContext

此成員會儲存會話的時鐘類型。下表包含可能的值。

值	描述
1	性能計數器值 (也稱為 QPC、QueryPerformanceCounter 或 PerfCounter)
2	系統定時器
3	CPU 週期

Flags

這個成員指出包含 WNODE_HEADER結構的 WNODE_XXX 結構類型：

WNODE_FLAG_ALL_DATA

WNODE_ALL_DATA結構的其餘部分會遵循緩衝區中的WNODE_HEADER結構。

WMI 會在WNODE_HEADER 結構中設定此旗標，此旗標會與 IRP_MN_QUERY_ALL_DATA 要求一起傳遞。

驅動程式會在事件 WNODE_HEADER 結構中設定此旗標，該事件是由數據區塊的所有實例所組成。如果所有數據實例的數據區塊大小都相同，驅動程式也會設定WNODE_FLAG_FIXED_INSTANCE_SIZE。

WNODE_FLAG_EVENT_ITEM

驅動程式會設定此旗標，指出 WNODE_XXX 結構已產生為事件。只有在同時設定WNODE_FLAG_ALL_DATA、WNODE_FLAG_SINGLE_INSTANCE或WNODE_FLAG_SINGLE_ITEM時，此旗標才有效。

WNODE_FLAG_EVENT_REFERENCE

WNODE_EVENT_REFERENCE 結構的其餘部分會遵循緩衝區中的 WNODE_HEADER 結構。

驅動程式會在產生大於事件登錄中所指定大小上限的事件時，設定此旗標。 WMI 會使用 WNODE_EVENT_REFERENCE 結構中的資訊來要求事件數據，並根據WNODE_FLAG_SEVERITY_MASK的值排程這類要求。

WNODE_FLAG_METHOD_ITEM

其餘 WNODE_METHOD_ITEM 結構會遵循緩衝區中的 WNODE_HEADER 結構。

WMI 會在WNODE_HEADER 結構中設定此旗標，此旗標會與 IRP_MN_EXECUTE_METHOD 要求一起傳遞。

WNODE_FLAG_SINGLE_INSTANCE

其餘 WNODE_SINGLE_INSTANCE 結構會遵循緩衝區中的 WNODE_HEADER 結構。

WMI 會在 WNODE_HEADER 結構中設定此旗標，此旗標會隨著查詢或變更實例的要求一起傳遞。

驅動程式會在由單一數據區塊實例所組成的事件 WNODE_HEADER 結構中設定此旗標。

WNODE_FLAG_SINGLE_ITEM

其餘 WNODE_SINGLE_INSTANCE 結構會遵循緩衝區中的 WNODE_HEADER 結構。

WMI 會在 WNODE_HEADER 結構中設定此旗標，此旗標會隨著變更專案的要求一起傳遞。

驅動程式會在由單一數據項組成的事件 WNODE_HEADER 結構中設定此旗標。

WNODE_FLAG_TOO_SMALL

WNODE_TOO_SMALL 結構的其餘部分會遵循緩衝區中的 WNODE_HEADER 結構。

驅動程式會在傳遞 WNODE_TOO_SMALL 結構時設定此旗標，表示緩衝區太小，無法傳回所有 WNODE_XXX 數據。

此外，旗標可能會使用下列一或多個旗標來設定，以提供 WNODE_XXX的其他資訊：

WNODE_FLAG_FIXED_INSTANCE_SIZE

數據區塊的所有實例的大小都相同。只有在同時設定WNODE_FLAG_ALL_DATA時，這個旗標才有效。

WNODE_FLAG_INSTANCES_SAME

要傳回 之WNODE_ALL_DATA 結構中的實例數目和動態實例名稱，與從上一個WNODE_ALL_DATA查詢傳回的實例數目相同。只有在同時設定WNODE_FLAG_ALL_DATA時，這個旗標才有效。針對使用靜態實例名稱註冊的數據區塊，會忽略此旗標。

為了達到優化效能，如果驅動程式可以追蹤其數據區塊數目或名稱的變更，驅動程式應該設定此旗標。然後 WMI 可以略過偵測和更新動態實例名稱所需的處理。

WNODE_FLAG_STATIC_INSTANCE_NAMES

要傳回 WNODE_XXX 數據不包含實例名稱。

WMI 會先設定此旗標，再針對使用靜態實例名稱註冊的數據區塊要求 WNODE_XXX 數據。從驅動程式收到傳回 的 WNODE_XXX 之後，WMI 會先填入註冊中指定的靜態實例名稱，再將傳回 的 WNODE_XXX 傳遞給數據取用者。

WNODE_FLAG_PDO_INSTANCE_NAMES

靜態實例名稱是以裝置 PDO 的裝置實例標識碼為基礎。驅動程式會藉由在 WMIREGGUID 中設定WMIREG_FLAG_INSTANCE_PDO來要求這類名稱，以用來註冊區塊。

WMI 會先設定此旗標，再針對以 PDO 為基礎的實例名稱註冊的數據區塊要求 WNODE_XXX 數據。

WNODE_FLAG_SEVERITY_MASK

與傳回 WNODE_EVENT_REFERENCE相關聯之事件的驅動程序判斷嚴重性層級，0x00表示最嚴重且0xff表示最嚴重層級。

WMI 會使用這個旗標的值來設定事件數據要求的優先順序。

WNODE_FLAG_USE_TIMESTAMP

系統記錄器不應修改驅動程式所設定 的 TimeStamp 值。

NT 驅動程式也可以將旗標設定為下列一或多個值，以便將事件區塊寫入系統記錄檔：

WNODE_FLAG_LOG_WNODE

事件區塊會傳送至系統記錄器。事件標頭是標準 WNODE_HEADER 結構。如果驅動程式清除WNODE_FLAG_TRACED_GUID，區塊也會傳送至 WMI，以傳遞至已啟用事件的任何數據取用者。驅動程式必須從集區內存配置 WNODE_XXX 。 WMI 會將事件傳遞給數據取用者之後釋放記憶體。

WNODE_FLAG_TRACED_GUID

事件區塊只會傳送至系統記錄器。它不會傳送給 WMI 數據取用者。事件標頭是在 Evntrace.h 中宣告的EVENT_TRACE_HEADER結構，而不是 WNODE_HEADER。驅動程式必須配置 WNODE_XXX 的記憶體，並在 IoWMIWriteEvent 傳回之後釋放它。如果驅動程式建立和維護自己的線程集區，驅動程式可以從驅動程式的線程本機記憶體配置這類記憶體，或將配置和釋放記憶體的額外負荷降到最低。

WNODE_FLAG_USE_GUID_PTR

Guid 成員指向記憶體中的 GUID，而不是包含 GUID 本身。系統記錄器會先取值指標，再將數據傳遞至取用者。只有在同時設定WNODE_FLAG_LOG_WNODE或WNODE_FLAG_TRACED_GUID時，此旗標才有效。

WNODE_FLAG_USE_MOF_PTR

遵循 WNODE_XXX 結構的固定成員的數據是由 Evntrace.h 中定義的MOF_FIELD結構陣列所組成，其中包含數據和大小的指標，而不是數據本身。陣列最多可以包含MAX_MOF_FIELD個元素。系統記錄器會先取值指標，再將數據傳遞至取用者此旗標僅適用於向 WMIREG_FLAG_TRACED_GUID 註冊的區塊。

備註

在 IRP_MN_CHANGE_XXX 或IRP_MN_EXECUTE_METHOD要求中，IRP 中的 BufferSize 表示輸出緩衝區的大小上限，而這類要求的輸入WNODE_HEADER中的 BufferSize 則表示緩衝區中輸入數據的大小，以位元組為單位。