WNODE_HEADER-Struktur (wmistr.h)

Artikel
08/08/2023

Die WNODE_HEADER-Struktur ist das erste Element aller anderen WNODE_XXX-Strukturen . Es enthält Informationen, die allen solchen Strukturen gemeinsam sind.

Syntax

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;

Member

BufferSize

Dieser Member gibt die Größe des nicht auslagerten Puffers in Byte an, um alle WNODE_ zurückgegebenenXXX-Daten zu empfangen, einschließlich dieser WNODE_HEADER-Struktur , zusätzliche Member einer WNODE_XXX-Struktur des durch Flags angegebenen Typs und alle WMI- oder treiberbestimmten Daten, die dieser Struktur zugeordnet sind.

ProviderId

Wenn Flags auf WNODE_FLAG_EVENT_ITEM oder WNODE_FLAG_EVENT_REFERENCE festgelegt ist, sollte ProviderId die ID des WMI-Anbieters enthalten, der dem Geräteobjekt zugeordnet ist. Sie können den ProviderId-Wert abrufen, indem Sie IoWMIDeviceObjectToProviderId aufrufen. Wenn Flags auf einen anderen Wert festgelegt ist, ist dieser Member reserviert.

DUMMYUNIONNAME

DUMMYUNIONNAME.HistoricalContext

Dieses Mitglied speichert das Handle in der Ereignisablaufverfolgungssitzung.

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Version

Dieses Element ist für WMI reserviert.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Linkage

Dieses Element ist für WMI reserviert.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.CountLost

Reserviert

DUMMYUNIONNAME2.KernelHandle

Dieses Element ist für WMI reserviert.

DUMMYUNIONNAME2.TimeStamp

Dieser Member gibt den Zeitpunkt an, zu dem ein Treiber die WNODE_XXX-Daten erfasst hat. Dieser Zeitwert wird im absoluten Systemzeitformat ausgedrückt. Die absolute Systemzeit ist die Anzahl der 100-Nanosekunden-Intervalle seit Beginn des Jahres 1601 im gregorianischen Kalender. Ein Treiber kann KeQuerySystemTime aufrufen, um diesen Wert zu erhalten. Wenn der Block in eine Protokolldatei (WNODE_FLAG_LOG_WNODE) geschrieben werden soll, kann ein NT-Treiber auch WNODE_FLAG_USE_TIMESTAMP in Flags festlegen, um anzufordern, dass die Systemprotokollierung den Wert von TimeStamp unverändert lässt.

Guid

Dieses Element gibt die GUID an, die den datenblock darstellt, der dem zurückzugebenden WNODE_XXX zugeordnet ist.

ClientContext

Dieses Mitglied speichert den Uhrtyp für die Sitzung. Mögliche Werte sind in der folgenden Tabelle enthalten.

Wert	BESCHREIBUNG
1	Leistungsindikatorwert (auch als QPC, QueryPerformanceCounter oder PerfCounter bezeichnet)
2	Systemtimer
3	CPU-Zyklus

Flags

Dieser Member gibt den Typ der WNODE_XXX-Struktur an, die die WNODE_HEADER-Struktur enthält:

WNODE_FLAG_ALL_DATA

Der Rest einer WNODE_ALL_DATA-Struktur folgt der WNODE_HEADER-Struktur im Puffer.

WMI legt dieses Flag in der WNODE_HEADER-Struktur fest, die es mit einer IRP_MN_QUERY_ALL_DATA-Anforderung übergibt.

Ein Treiber legt dieses Flag in der WNODE_HEADER-Struktur eines Ereignisses fest, das aus allen Instanzen eines Datenblocks besteht. Wenn die Datenblockgröße für alle Instanzen identisch ist, legt ein Treiber auch WNODE_FLAG_FIXED_INSTANCE_SIZE fest.

WNODE_FLAG_EVENT_ITEM

Ein Treiber legt dieses Flag fest, um anzugeben, dass die WNODE_XXX-Struktur als Ereignis generiert wurde. Dieses Flag ist nur gültig, wenn WNODE_FLAG_ALL_DATA, WNODE_FLAG_SINGLE_INSTANCE oder WNODE_FLAG_SINGLE_ITEM ebenfalls festgelegt ist.

WNODE_FLAG_EVENT_REFERENCE

Der Rest einer WNODE_EVENT_REFERENCE-Struktur folgt der WNODE_HEADER-Struktur im Puffer.

Ein Treiber legt dieses Flag fest, wenn er ein Ereignis generiert, das größer als die in der Registrierung für ein Ereignis angegebene maximale Größe ist. WMI verwendet die Informationen in der WNODE_EVENT_REFERENCE-Struktur , um die Ereignisdaten anzufordern, und plant eine solche Anforderung entsprechend dem Wert von WNODE_FLAG_SEVERITY_MASK.

WNODE_FLAG_METHOD_ITEM

Der Rest einer WNODE_METHOD_ITEM-Struktur folgt der WNODE_HEADER-Struktur im Puffer.

WMI legt dieses Flag in der WNODE_HEADER-Struktur fest, die mit einer IRP_MN_EXECUTE_METHOD-Anforderung übergeben wird.

WNODE_FLAG_SINGLE_INSTANCE

Der Rest einer WNODE_SINGLE_INSTANCE-Struktur folgt der WNODE_HEADER-Struktur im Puffer.

WMI legt dieses Flag in der WNODE_HEADER-Struktur fest, die mit einer Anforderung zum Abfragen oder Ändern eines instance übergeben wird.

Ein Treiber legt dieses Flag in der WNODE_HEADER-Struktur eines Ereignisses fest, das aus einem einzelnen instance eines Datenblocks besteht.

WNODE_FLAG_SINGLE_ITEM

Der Rest einer WNODE_SINGLE_INSTANCE-Struktur folgt der WNODE_HEADER-Struktur im Puffer.

WMI legt dieses Flag in der WNODE_HEADER-Struktur fest, die mit einer Anforderung zum Ändern eines Elements übergeben wird.

Ein Treiber legt dieses Flag in der WNODE_HEADER-Struktur eines Ereignisses fest, das aus einem einzelnen Datenelement besteht.

WNODE_FLAG_TOO_SMALL

Der Rest einer WNODE_TOO_SMALL-Struktur folgt der WNODE_HEADER-Struktur im Puffer.

Ein Treiber legt dieses Flag fest, wenn er eine WNODE_TOO_SMALL-Struktur übergibt, was angibt, dass der Puffer zu klein ist, um alle WNODE_XXX-Daten zurückzugeben.

Darüber hinaus können Flags mit einem oder mehreren der folgenden Flags festgelegt werden, die zusätzliche Informationen zum WNODE_XXX bereitstellen:

WNODE_FLAG_FIXED_INSTANCE_SIZE

Alle Instanzen eines Datenblocks haben die gleiche Größe. Dieses Flag ist nur gültig, wenn WNODE_FLAG_ALL_DATA ebenfalls festgelegt ist.

WNODE_FLAG_INSTANCES_SAME

Die Anzahl der Instanzen und die namen der dynamischen instance in einer WNODE_ALL_DATA-Struktur, die zurückgegeben werden sollen, sind identisch mit denen, die aus der vorherigen WNODE_ALL_DATA Abfrage zurückgegeben wurden. Dieses Flag ist nur gültig, wenn WNODE_FLAG_ALL_DATA ebenfalls festgelegt ist. Dieses Flag wird für Datenblöcke ignoriert, die mit statischen instance Namen registriert sind.

Um die Leistung zu optimieren, sollte ein Treiber dieses Flag festlegen, wenn er Änderungen an der Anzahl oder den Namen seiner Datenblöcke nachverfolgen kann. WMI kann dann die Verarbeitung überspringen, die zum Erkennen und Aktualisieren dynamischer instance Namen erforderlich ist.

WNODE_FLAG_STATIC_INSTANCE_NAMES

Die WNODE_XXX-Daten, die zurückgegeben werden sollen, enthalten keine instance Namen.

WMI legt dieses Flag fest, bevor WNODE_XXX-Daten für Datenblöcke angefordert werden, die mit statischen instance-Namen registriert sind. Nach dem Empfang des zurückgegebenen WNODE_XXX vom Treiber füllt WMI die bei der Registrierung angegebenen statischen instance Namen aus, bevor der zurückgegebene WNODE_XXX an einen Datenconsumer übergeben wird.

WNODE_FLAG_PDO_INSTANCE_NAMES

Statische instance Namen basieren auf der Geräte-instance-ID des PDO für das Gerät. Ein Treiber fordert solche Namen an, indem er WMIREG_FLAG_INSTANCE_PDO in der WMIREGGUID festlegt, die er zum Registrieren des Blocks verwendet.

WMI legt dieses Flag fest, bevor WNODE_XXX-Daten für Datenblöcke angefordert werden, die mit PDO-basierten instance-Namen registriert sind.

WNODE_FLAG_SEVERITY_MASK

Der vom Treiber bestimmte Schweregrad des Ereignisses, das einem zurückgegebenen WNODE_EVENT_REFERENCE zugeordnet ist, wobei 0x00 den geringsten Schweregrad und 0xff die schwerwiegendste Stufe angibt.

WMI verwendet den Wert dieses Flags, um seine Anforderungen für die Ereignisdaten zu priorisieren.

WNODE_FLAG_USE_TIMESTAMP

Die Systemprotokollierung sollte den vom Treiber festgelegten TimeStamp-Wert nicht ändern.

Ein NT-Treiber kann flags auch auf einen oder mehrere der folgenden Werte für Ereignisblöcke festlegen, die in eine Systemprotokolldatei geschrieben werden sollen:

WNODE_FLAG_LOG_WNODE

Ein Ereignisblock wird an die Systemprotokollierung gesendet. Der Ereignisheader ist eine Standardstruktur WNODE_HEADER . Wenn der Treiber WNODE_FLAG_TRACED_GUID löscht, wird der Block auch an WMI zur Übermittlung an alle Datenconsumer gesendet, die das Ereignis aktiviert haben. Der Treiber muss den WNODE_XXX aus dem Poolspeicher zuordnen. WMI gibt den Arbeitsspeicher frei, nachdem das Ereignis an Datenconsumer ausgeliefert wurde.

WNODE_FLAG_TRACED_GUID

Ein Ereignisblock soll nur an die Systemprotokollierung gesendet werden. Es wird nicht an WMI-Datenconsumer gesendet. Der Ereignisheader ist eine EVENT_TRACE_HEADER-Struktur , die in Evntrace.h deklariert wird, anstatt eine WNODE_HEADER. Der Treiber muss Arbeitsspeicher für die WNODE_XXX zuweisen und nach der Rückgabe von IoWMIWriteEvent freigeben. Der Treiber kann diesen Arbeitsspeicher entweder aus dem Stapel oder aus dem lokalen Speicher des Treibers aus dem threadlokalen Speicher des Treibers zuordnen, wenn der Treiber einen eigenen Threadpool erstellt und verwaltet, um den Mehraufwand für die Zuweisung und Freigabe des Arbeitsspeichers zu minimieren.

WNODE_FLAG_USE_GUID_PTR

Der Guid-Member verweist auf eine GUID im Arbeitsspeicher, anstatt die GUID selbst zu enthalten. Die Systemprotokollierung leitet den Zeiger ab, bevor die Daten an den Consumer übergeben werden. Dieses Flag ist nur gültig, wenn WNODE_FLAG_LOG_WNODE oder WNODE_FLAG_TRACED_GUID ebenfalls festgelegt sind.

WNODE_FLAG_USE_MOF_PTR

Daten, die den festen Membern einer WNODE_XXX-Struktur folgen, bestehen aus einem Array von MOF_FIELD Strukturen, die in Evntrace.h definiert sind und nicht die Daten selbst, sondern Zeiger auf Daten und Größen enthalten. Das Array kann bis zu MAX_MOF_FIELD Elemente enthalten. Die Systemprotokollierung leitet die Zeiger ab, bevor die Daten an den Consumer übergeben werden. Dieses Flag ist nur für Blöcke gültig, die mit WMIREG_FLAG_TRACED_GUID registriert sind.

Hinweise

In einer IRP_MN_CHANGE_XXX- oder IRP_MN_EXECUTE_METHOD-Anforderung gibt BufferSize im IRP die maximale Größe des Ausgabepuffers in Bytes an, während BufferSize im Eingabe-WNODE_HEADER für eine solche Anforderung die Größe der Eingabedaten im Puffer in Bytes angibt.