Structures WMI WNODE_XXX

WMI utilise un ensemble de structures de données standard appelées WNODE_XXX pour transmettre des données entre les consommateurs de données en mode utilisateur et les fournisseurs de données en mode noyau, tels que les pilotes. Si un pilote gère les requêtes WMI en appelant WmiSystemControl, le pilote n’est pas nécessaire pour lire ou écrire des structures WNODE_XXX. Sinon, le pilote doit interpréter l’entrée WNODE_XXX à Parameters.WMI.Buffer et/ou écrire une sortie WNODE_XXX à cet emplacement.

Le tableau suivant répertorie les adresses IP VIRTUELLES WMI et leurs structuresXXX WNODE_correspondantes.

WMI IRP	Structure WNODE_XXX associée
IRP_MN_CHANGE_SINGLE_INSTANCE	WNODE_SINGLE_INSTANCE
IRP_MN_CHANGE_SINGLE_ITEM	WNODE_SINGLE_ITEM
IRP_MN_EXECUTE_METHOD	WNODE_METHOD_ITEM
IRP_MN_QUERY_ALL_DATA	WNODE_ALL_DATA
IRP_MN_QUERY_SINGLE_INSTANCE	WNODE_SINGLE_INSTANCE

Deux structures supplémentaires WNODE_XXX, WNODE_EVENT_ITEM et WNODE_EVENT_REFERENCE, sont utilisées pour envoyer des notifications d’événements activés. Un pilote qui inscrit des blocs d’événements, si un événement est activé et que l’événement se produit, envoie une notification de l’événement à WMI en appelant IoWMIWriteEvent et en passant une structureXXX WNODE_EVENT_. Pour plus d’informations sur l’envoi d’événements WMI, consultez Envoi d’événements WMI.

Chaque structure WNODE_XXX se compose des éléments suivants :

• Structure incorporée WNODE_HEADER qui contient des informations communes à tous les WNODE_XXX, y compris la taille de la mémoire tampon, le GUID qui représente le bloc de données et les indicateurs qui indiquent le type de structureXXX WNODE_XXX, qu’il utilise des noms d’instances statiques ou dynamiques, et d’autres caractéristiques du bloc.

• Les membres fixes de la structureXXX WNODE_particulière, telles que les décalages vers les noms d’instance et les données.

Une structure WNODE_XXX dans une mémoire tampon IRP (Parameters.WMI.Buffer) est généralement suivie de données variables liées à la requête, telles que les noms d’instances dynamiques, les chaînes de noms d’instance statique, l’entrée ou la sortie d’une méthode, ou des données pour une ou plusieurs instances d’un bloc de données. La taille de la mémoire tampon doit donc dépasser sizeof(WNODE_XXX) par la quantité de données variables impliquées.

Notez que WMI n’effectue pas la vérification de type sur les données de variables fournies par un pilote. Le pilote doit aligner les données de sortie sur une limite appropriée dans la mémoire tampon de sortie afin qu’un consommateur de données puisse analyser correctement les données. En particulier, chaque instance doit démarrer sur une limite de 8 octets et chacun de ses éléments doit être aligné sur une limite naturelle en fonction du schéma de bloc de données précédemment inscrit par le pilote. Les noms d’instances dynamiques peuvent être alignés sur une limite de 2 octets.

La figure suivante montre un diagramme de bloc d’une mémoire tampon IRP contenant une structure WNODE_SINGLE_INSTANCE qu’un pilote peut retourner en réponse à une demande de IRP_MN_QUERY_SINGLE_INSTANCE.

En haut de la figure précédente :

• La structure WNODE_HEADER au début de la WNODE_SINGLE_INSTANCE est contenue dans un membre WnodeHeader. WMI renseigne tous les membres de l'WNODE_HEADER avant d’envoyer la demande. Dans la WNODE_HEADER:

  • WnodeHeader.Buffersize indique la taille du WNODE_SINGLE_INSTANCE, y compris les données qui suivent les membres fixes de la structure. (La valeur de WnodeHeader.Buffersize est généralement inférieure à Parameters.WMI.Buffersize, ce qui indique la taille de la mémoire tampon allouée par WMI pour recevoir la sortie du pilote.)
  • WnodeHeader.Guid contient le GUID qui identifie le bloc de données.
  • Dans cet exemple, WnodeHeader.Flags indique que cette structure est un WNODE_SINGLE_INSTANCE et que le bloc de données utilise des noms d’instances statiques.

• Étant donné que le bloc de données utilise des noms d’instances statiques, WMI définit InstanceIndex à l’index de l’instance dans la liste des noms d’instances statiques passés par le pilote lorsqu’il a inscrit le bloc. OffsetInstanceNames n’est pas utilisé.

• WMI définit DataBlockOffset pour indiquer le décalage entre le début de la mémoire tampon et le premier octet des données d’instance. (Le pilote ne doit pas modifier cette valeur) Là encore, étant donné que le bloc de données utilise des noms d’instances statiques, ce décalage indique le même emplacement que VariableData. Si le bloc de données a utilisé des noms d’instances dynamiques, les noms d’instances commencent à VariableData et DataBlockOffset spécifient un décalage plus important dans la mémoire tampon.

• Le pilote définit SizeDataBlock le nombre d’octets des données d’instance retournées.

• À VariableData (après les données de nom d’instance, le cas échéant), le pilote écrit les données d’instance de l’instance demandée dans la mémoire tampon de sortie.

Un pilote lit et écrit WNODE_METHOD_ITEM et WNODE_SINGLE_ITEM structures de la même façon que WNODE_SINGLE_INSTANCE. Ces structures ressemblent les unes aux autres dans le fait que chacun a les membres fixes OffsetInstanceName, InstanceIndex, DataBlockOffset, SizeDataBlock (ou, dans le cas de WNODE_SINGLE_ITEM, SizeDataItem) et VariableData. WNODE_METHOD_ITEM comprend un MethodId et WNODE_SINGLE_ITEM inclut un ItemId qui WNODE_SINGLE_INSTANCE manque.

WNODE_ALL_DATA diffère des structures précédentes dans lesquelles il est utilisé pour passer plusieurs instances d’un bloc de données, y compris éventuellement des noms d’instances dynamiques et éventuellement des tailles différentes.

La figure suivante montre un diagramme de bloc d’une mémoire tampon IRP contenant un WNODE_ALL_DATA qu’un pilote peut retourner en réponse à une demande de IRP_MN_QUERY_ALL_DATA.

En haut de la figure précédente :

• Comme décrit dans la figure précédente, la structure WNODE_HEADER au début de la WNODE_ALL_DATA est contenue dans un membre WnodeHeader. WnodeHeader.Buffersize et WnodeHeader.Guid indiquer la taille du WNODE_ALL_DATA et le GUID du bloc de données, respectivement.

  Dans cet exemple, WMI définit WnodeHeader.Flags pour indiquer que cette structure est un WNODE_ALL_DATA et que le bloc de données a été inscrit avec des noms d’instances dynamiques (autrement dit, WMI efface WNODE_FLAG_STATIC_INSTANCE_NAMES et WNODE_FLAG_PDO_INSTANCE_NAMES). En sortie, le pilote définit WNODE_FLAG_FIXED_INSTANCE_SIZE pour indiquer que toutes les instances sont de la même taille.

• WMI définit DataBlockOffset pour indiquer le décalage entre le début de la mémoire tampon et le premier octet des données d’instance. (Le pilote ne doit pas modifier cette valeur). Dans cet exemple, les données d’instance suivent les noms d’instances à OffsetInstanceNameOffsets.

• Le pilote définit InstanceCount pour indiquer le nombre d’instances retournées.

• WNODE_XXX pour les blocs de données qui utilisent des noms d’instances dynamiques contiennent toujours les chaînes de nom d’instance. Étant donné que cet exemple utilise des noms d’instances dynamiques, OffsetInstanceNameOffsets indique le décalage entre le début de la mémoire tampon et un tableau de décalages vers des noms d’instances dynamiques dans la mémoire tampon.

• FixedInstanceSize indique le nombre d’octets de données dans chaque instance retournée par le pilote. Si les instances de ce bloc de données devaient varier en taille, le pilote efface WNODE_FLAG_FIXED_INSTANCE_SIZE dans WnodeHeader.Flags et définit OffsetInstanceDataAndLength à un tableau de structures OFFSETINSTANCEDATAANDLENGTH, chacun spécifiant un décalage sur les données d’une instance et le nombre d’octets de cette instance au lieu de définir FixedInstanceSize.

Pour plus d’informations sur WNODE_structures XXX, consultez structures système.