WNODE_HEADER 结构 (wmistr.h)

项目
08/08/2023

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结构、标志所指示类型的 WNODE_XXX 结构的其他成员，以及伴随该结构的任何 WMI 或驱动程序确定的数据。

ProviderId

如果 Flags 设置为 WNODE_FLAG_EVENT_ITEM 或 WNODE_FLAG_EVENT_REFERENCE， 则 ProviderId 应包含与设备对象关联的 WMI 提供程序的 ID。可以通过调用 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

此成员指示表示与要返回的 WNODE_XXX 关联的数据块的 GUID。

ClientContext

此成员存储会话的时钟类型。下表中包括了可能的值。

值	说明
1	性能计数器值 (也称为 QPC、QueryPerformanceCounter 或 PerfCounter)
2	系统计时器
3	CPU 周期

Flags

此成员指示包含 WNODE_HEADER 结构的 WNODE_XXX 结构的类型：

WNODE_FLAG_ALL_DATA

WNODE_ALL_DATA结构的其余部分遵循缓冲区中的WNODE_HEADER结构。

WMI 在 它随IRP_MN_QUERY_ALL_DATA 请求传递的WNODE_HEADER结构中设置此标志。

驱动程序在由数据块的所有实例组成的事件的 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 在 它随IRP_MN_EXECUTE_METHOD 请求一起传递的WNODE_HEADER结构中设置此标志。

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 的设备实例 ID。驱动程序通过在用于注册块的 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 驱动程序还可以将 Flags 设置为以下一个或多个值，以便将事件块写入系统日志文件：

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 指示缓冲区中输入数据的大小（以字节为单位）。