структура 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, связанного с объектом устройства. Значение ProviderId можно получить, вызвав IoWMIDeviceObjectToProviderId. Если параметру Flags присвоено любое другое значение, этот элемент зарезервирован.

DUMMYUNIONNAME

DUMMYUNIONNAME.HistoricalContext

Этот член сохраняет дескриптор в сеансе трассировки событий.

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Version

Этот член зарезервирован для WMI.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Linkage

Этот член зарезервирован для WMI.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.CountLost

Зарезервировано

DUMMYUNIONNAME2.KernelHandle

Этот член зарезервирован для WMI.

DUMMYUNIONNAME2.TimeStamp

Этот элемент указывает время сбора драйвером данных WNODE_XXX . Это значение времени выражается в абсолютном формате системного времени. Абсолютное системное время — это число 100-наносекундных интервалов с начала 1601 года в григорианском календаре. Драйвер может вызвать KeQuerySystemTime , чтобы получить это значение. Если блок должен быть записан в файл журнала (WNODE_FLAG_LOG_WNODE), драйвер NT также может задать WNODE_FLAG_USE_TIMESTAMP в разделе Флаги , чтобы запросить, чтобы средство ведения журнала системы оставило значение TimeStamp без изменений.

Guid

Этот элемент указывает GUID, представляющий блок данных, связанный с возвращаемым WNODE_XXX .

ClientContext

Этот член сохраняет тип часов для сеанса. Возможные значения приведены в следующей таблице.

Значение	Описание
1	Значение счетчика производительности (также называемое QPC, QueryPerformanceCounter или PerfCounter)
2	Системный таймер
3	Цикл ЦП

Flags

Этот элемент указывает тип структуры WNODE_XXX , содержащей структуру WNODE_HEADER:

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 для устройства. Драйвер запрашивает такие имена, задав WMIREG_FLAG_INSTANCE_PDO в WMIREGGUID , который он использует для регистрации блока.

WMI устанавливает этот флаг перед запросом данных WNODE_XXX для блоков данных, зарегистрированных с именами экземпляров на основе PDO.

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. Заголовок события представляет собой EVENT_TRACE_HEADER структуру, объявленную в Evntrace.h, а не 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, состоят из массива MOF_FIELD структур, определенных в Evntrace.h, которые содержат указатели на данные и размеры, а не сами данные. Массив может содержать до MAX_MOF_FIELD элементов. Средство ведения журнала системы разыменовывает указатели перед передачей данных потребителю Этот флаг действителен только для блоков, зарегистрированных с помощью WMIREG_FLAG_TRACED_GUID.

В запросе IRP_MN_CHANGE_XXX или IRP_MN_EXECUTE_METHODbufferSize в IRP указывает максимальный размер выходного буфера в байтах, а BufferSize во входном WNODE_HEADER для такого запроса указывает размер входных данных в байтах в буфере.