WNODE_HEADER structure (wmistr.h)

Article
02/27/2024

La structure WNODE_HEADER est le premier membre de toutes les autres structures WNODE_XXX . Il contient des informations communes à toutes ces structures.

Syntaxe

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;

Membres

BufferSize

Ce membre spécifie la taille, en octets, de la mémoire tampon non paginé à recevoir toutes les données WNODE_XXX à retourner, y compris cette structure WNODE_HEADER , les membres supplémentaires d’une structure WNODE_XXX du type indiqué par les indicateurs et toutes les données WMI ou déterminées par le pilote qui accompagnent cette structure.

ProviderId

Si Indicateurs est défini sur WNODE_FLAG_EVENT_ITEM ou WNODE_FLAG_EVENT_REFERENCE, ProviderId doit contenir l’ID du fournisseur WMI associé à l’objet d’appareil. Vous pouvez obtenir la valeur ProviderId en appelant IoWMIDeviceObjectToProviderId. Si Flags est défini sur une autre valeur, ce membre est réservé.

DUMMYUNIONNAME

DUMMYUNIONNAME.HistoricalContext

Ce membre stocke le handle dans la session de suivi d’événements.

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Version

Ce membre est réservé à WMI.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.Linkage

Ce membre est réservé à WMI.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.CountLost

Réservé

DUMMYUNIONNAME2.KernelHandle

Ce membre est réservé à WMI.

DUMMYUNIONNAME2.TimeStamp

Ce membre indique l’heure à laquelle un pilote a collecté les données WNODE_XXX . Cette valeur de temps est exprimée au format d’heure système absolu. L’heure système absolue est le nombre d’intervalles de 100 nanosecondes depuis le début de l’année 1601 dans le calendrier grégorien. Un pilote peut appeler KeQuerySystemTime pour obtenir cette valeur. Si le bloc doit être écrit dans un fichier journal (WNODE_FLAG_LOG_WNODE), un pilote NT peut également définir WNODE_FLAG_USE_TIMESTAMP dans Indicateurs pour demander que l’enregistreur d’événements système laisse la valeur de TimeStamp inchangée.

Guid

Ce membre indique le GUID qui représente le bloc de données associé au WNODE_XXX à retourner.

ClientContext

Ce membre stocke le type d’horloge de la session. Les valeurs possibles sont incluses dans le tableau suivant.

Valeur	Description
1	Valeur du compteur de performances (également appelée QPC, QueryPerformanceCounter ou PerfCounter)
2	Minuteur système
3	Cycle du processeur

Flags

Ce membre indique le type de structure WNODE_XXX qui contient la structure WNODE_HEADER :

WNODE_FLAG_ALL_DATA

Le reste d’une structure WNODE_ALL_DATA suit la structure WNODE_HEADER dans la mémoire tampon.

WMI définit cet indicateur dans la structure WNODE_HEADER qu’il transmet avec une requête IRP_MN_QUERY_ALL_DATA .

Un pilote définit cet indicateur dans la structure WNODE_HEADER d’un événement qui se compose de toutes les instances d’un bloc de données. Si la taille du bloc de données est identique pour toutes les instances, un pilote définit également WNODE_FLAG_FIXED_INSTANCE_SIZE.

WNODE_FLAG_EVENT_ITEM

Un pilote définit cet indicateur pour indiquer que la structure WNODE_XXX a été générée en tant qu’événement. Cet indicateur est valide uniquement si WNODE_FLAG_ALL_DATA, WNODE_FLAG_SINGLE_INSTANCE ou WNODE_FLAG_SINGLE_ITEM est également défini.

WNODE_FLAG_EVENT_REFERENCE

Le reste d’une structure de WNODE_EVENT_REFERENCE suit la structure WNODE_HEADER dans la mémoire tampon.

Un pilote définit cet indicateur lorsqu’il génère un événement supérieur à la taille maximale spécifiée dans le Registre pour un événement. WMI utilise les informations de la structure WNODE_EVENT_REFERENCE pour demander les données d’événement et planifie une telle demande en fonction de la valeur de WNODE_FLAG_SEVERITY_MASK.

WNODE_FLAG_METHOD_ITEM

Le reste d’une structure de WNODE_METHOD_ITEM suit la structure WNODE_HEADER dans la mémoire tampon.

WMI définit cet indicateur dans la structure WNODE_HEADER qu’il transmet avec une requête IRP_MN_EXECUTE_METHOD .

WNODE_FLAG_SINGLE_INSTANCE

Le reste d’une structure WNODE_SINGLE_INSTANCE suit la structure WNODE_HEADER dans la mémoire tampon.

WMI définit cet indicateur dans la structure WNODE_HEADER qu’il transmet avec une demande d’interrogation ou de modification d’un instance.

Un pilote définit cet indicateur dans la structure WNODE_HEADER d’un événement qui se compose d’un seul instance d’un bloc de données.

WNODE_FLAG_SINGLE_ITEM

Le reste d’une structure WNODE_SINGLE_INSTANCE suit la structure WNODE_HEADER dans la mémoire tampon.

WMI définit cet indicateur dans la structure WNODE_HEADER qu’il transmet avec une demande de modification d’un élément.

Un pilote définit cet indicateur dans la structure WNODE_HEADER d’un événement qui se compose d’un seul élément de données.

WNODE_FLAG_TOO_SMALL

Le reste d’une structure de WNODE_TOO_SMALL suit la structure WNODE_HEADER dans la mémoire tampon.

Un pilote définit cet indicateur lorsqu’il passe une structure de WNODE_TOO_SMALL , indiquant que la mémoire tampon est trop petite pour que toutes les données WNODE_XXX soient retournées.

En outre, les indicateurs peuvent être définis avec un ou plusieurs des indicateurs suivants qui fournissent des informations supplémentaires sur le WNODE_XXX :

WNODE_FLAG_FIXED_INSTANCE_SIZE

Toutes les instances d’un bloc de données ont la même taille. Cet indicateur n’est valide que si WNODE_FLAG_ALL_DATA est également défini.

WNODE_FLAG_INSTANCES_SAME

Le nombre d’instances et les noms de instance dynamiques dans une structure WNODE_ALL_DATA à retourner sont identiques à ceux retournés par la requête WNODE_ALL_DATA précédente. Cet indicateur n’est valide que si WNODE_FLAG_ALL_DATA est également défini. Cet indicateur est ignoré pour les blocs de données inscrits avec des noms instance statiques.

Pour optimiser les performances, un pilote doit définir cet indicateur s’il peut suivre les modifications apportées au nombre ou aux noms de ses blocs de données. WMI peut ensuite ignorer le traitement requis pour détecter et mettre à jour les noms de instance dynamiques.

WNODE_FLAG_STATIC_INSTANCE_NAMES

Les données WNODE_XXX à retourner n’incluent pas de noms instance.

WMI définit cet indicateur avant de demander des données WNODE_XXX pour les blocs de données inscrits avec des noms de instance statiques. Après avoir reçu le WNODE_XXX retourné par le pilote, WMI remplit les noms de instance statiques spécifiés lors de l’inscription avant de transmettre le WNODE_XXX retourné à un consommateur de données.

WNODE_FLAG_PDO_INSTANCE_NAMES

Les noms de instance statiques sont basés sur l’ID de instance de l’AOP de l’appareil. Un pilote demande ces noms en définissant WMIREG_FLAG_INSTANCE_PDO dans le WMIREGGUID qu’il utilise pour inscrire le bloc.

WMI définit cet indicateur avant de demander des données WNODE_XXX pour les blocs de données inscrits avec des noms de instance PDO.

WNODE_FLAG_SEVERITY_MASK

Niveau de gravité déterminé par le pilote de l’événement associé à un WNODE_EVENT_REFERENCE retourné, 0x00 indiquant le niveau le moins grave et 0xff indiquant le niveau le plus grave.

WMI utilise la valeur de cet indicateur pour hiérarchiser ses demandes pour les données d’événement.

WNODE_FLAG_USE_TIMESTAMP

L’enregistreur d’événements système ne doit pas modifier la valeur de TimeStamp définie par le pilote.

Un pilote NT peut également définir indicateurs sur une ou plusieurs des valeurs suivantes pour que les blocs d’événements soient écrits dans un fichier journal système :

WNODE_FLAG_LOG_WNODE

Un bloc d’événements doit être envoyé à l’enregistreur d’événements système. L’en-tête d’événement est une structure de WNODE_HEADER standard. Si le pilote efface WNODE_FLAG_TRACED_GUID, le bloc est également envoyé à WMI pour être remis à tous les consommateurs de données qui ont activé l’événement. Le pilote doit allouer le WNODE_XXX à partir de la mémoire du pool. WMI libère la mémoire après avoir livré l’événement aux consommateurs de données.

WNODE_FLAG_TRACED_GUID

Un bloc d’événements doit être envoyé uniquement à l’enregistreur d’événements système. Il n’est pas envoyé aux consommateurs de données WMI. L’en-tête d’événement est une structure EVENT_TRACE_HEADER , déclarée dans Evntrace.h, au lieu d’une WNODE_HEADER. Le pilote doit allouer de la mémoire pour le WNODE_XXX et la libérer après le retour de IoWMIWriteEvent . Le pilote peut allouer cette mémoire à partir de la pile ou, pour réduire la surcharge liée à l’allocation et à la libération de la mémoire, au stockage local du thread du pilote si le pilote crée et gère son propre pool de threads.

WNODE_FLAG_USE_GUID_PTR

Le membre GUID pointe vers un GUID en mémoire, plutôt que de contenir le GUID lui-même. L’enregistreur d’événements système déréférence le pointeur avant de transmettre les données au consommateur. Cet indicateur n’est valide que si WNODE_FLAG_LOG_WNODE ou WNODE_FLAG_TRACED_GUID sont également définis.

WNODE_FLAG_USE_MOF_PTR

Les données qui suivent les membres fixes d’une structure WNODE_XXX se composent d’un tableau de structures MOF_FIELD, définies dans Evntrace.h, qui contiennent des pointeurs vers des données et des tailles plutôt que les données elles-mêmes. Le tableau peut contenir jusqu’à MAX_MOF_FIELD éléments. L’enregistreur d’événements système déréférence les pointeurs avant de transmettre les données au consommateur Cet indicateur est valide uniquement pour les blocs inscrits avec WMIREG_FLAG_TRACED_GUID.

Remarques

Dans une requête IRP_MN_CHANGE_XXX ou IRP_MN_EXECUTE_METHOD , BufferSize dans l’IRP indique la taille maximale en octets de la mémoire tampon de sortie, tandis que BufferSize dans la WNODE_HEADER d’entrée pour une telle demande indique la taille, en octets, des données d’entrée dans la mémoire tampon.