Strutture WNODE_XXX WMI

WMI usa un set di strutture di dati standard denominate WNODE_XXX per passare i dati tra consumer di dati in modalità utente e provider di dati in modalità kernel, ad esempio i driver. Se un driver gestisce le richieste WMI chiamando WmiSystemControl, il driver non è necessario per leggere o scrivere strutture WNODE_XXX. In caso contrario, il driver deve interpretare l'input WNODE_XXX in Parameters.WMI.Buffer e/o scrivere un output WNODE_XXX in tale posizione.

Nella tabella seguente sono elencati gli indirizzi IP WMI e le relative strutture WNODE_XXX corrispondenti.

WMI IRP	Struttura WNODE_XXX correlata
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

Due strutture WNODE_XXX aggiuntive, WNODE_EVENT_ITEM e WNODE_EVENT_REFERENCE, vengono usate per inviare notifiche degli eventi abilitati. Un driver che registra i blocchi di eventi, se un evento è abilitato e l'evento si verifica, inviare una notifica dell'evento a WMI chiamando IoWMIWriteEvent e passando una struttura WNODE_EVENT_XXX. Per informazioni sull'invio di eventi WMI, vedere Invio di eventi WMI.

Ogni struttura WNODE_XXX è costituita dal seguente:

• Struttura WNODE_HEADER incorporata che contiene informazioni comuni a tutti i WNODE_XXX, incluse le dimensioni del buffer, il GUID che rappresenta il blocco dati e i flag che indicano il tipo di struttura WNODE_XXX, indipendentemente dal fatto che usi nomi di istanze statiche o dinamiche e altre caratteristiche del blocco.

• Membri fissi della particolare struttura WNODE_XXX , ad esempio offset per nomi e dati dell'istanza.

Una struttura WNODE_XXX in un buffer IRP (Parameters.WMI.Buffer) viene in genere seguita da dati variabili correlati alla richiesta, ad esempio nomi di istanze dinamiche, stringhe di nome istanza statiche, input per o output da un metodo o dati per una o più istanze di un blocco di dati. Le dimensioni del buffer devono pertanto superare dimensioniof(WNODE_XXX) per la quantità di dati variabili coinvolti.

Si noti che WMI non esegue il controllo dei tipi sui dati delle variabili forniti da un driver. Il driver deve allineare i dati di output in un limite appropriato nel buffer di output in modo che un consumer di dati possa analizzare correttamente i dati. In particolare, ogni istanza deve iniziare su un limite di 8 byte e ognuno dei relativi elementi deve essere allineato su un limite naturale in base allo schema del blocco di dati registrato in precedenza dal driver. I nomi delle istanze dinamiche possono essere allineati su un limite di 2 byte.

La figura seguente mostra un diagramma a blocchi di un buffer IRP contenente una struttura WNODE_SINGLE_INSTANCE che un driver potrebbe restituire in risposta a una richiesta di IRP_MN_QUERY_SINGLE_INSTANCE .

A partire dalla parte superiore della figura precedente:

• La struttura WNODE_HEADER all'inizio della WNODE_SINGLE_INSTANCE è contenuta in un membro WnodeHeader . WMI compila tutti i membri del WNODE_HEADER prima di inviare la richiesta. Nella WNODE_HEADER:

  • WnodeHeader.Buffersize indica le dimensioni della WNODE_SINGLE_INSTANCE, inclusi i dati che seguono i membri fissi della struttura. Il valore di WnodeHeader.Buffersize è in genere minore di Parameters.WMI.Buffersize, che indica la dimensione del buffer allocata da WMI per ricevere l'output dal driver.
  • WnodeHeader.Guid contiene il GUID che identifica il blocco di dati.
  • In questo esempio WnodeHeader.Flags indica che questa struttura è una WNODE_SINGLE_INSTANCE e che il blocco di dati usa nomi di istanza statici.

• Poiché il blocco di dati usa nomi di istanza statici, WMI imposta InstanceIndex sull'indice dell'istanza nell'elenco dei nomi di istanza statici passati dal driver quando ha registrato il blocco. OffsetInstanceNames non viene usato.

• WMI imposta DataBlockOffset per indicare l'offset dall'inizio del buffer al primo byte dei dati dell'istanza. (Il driver non deve modificare questo valore) Anche perché il blocco di dati usa nomi di istanza statici, questo offset indica la stessa posizione di VariableData. Se il blocco di dati usato nomi di istanza dinamici, i nomi delle istanze iniziano in VariableData e DataBlockOffset specificano un offset maggiore nel buffer.

• Il driver imposta SizeDataBlock sul numero di byte di dati dell'istanza restituiti.

• In VariableData (dopo i dati del nome dell'istanza, se presente), il driver scrive i dati di istanza per l'istanza richiesta nel buffer di output.

Un driver legge e scrive WNODE_METHOD_ITEM e WNODE_SINGLE_ITEM strutture nello stesso modo di WNODE_SINGLE_INSTANCE. Queste strutture sono simili a quelle in cui ognuno ha i membri fissi OffsetInstanceName, InstanceIndex, DataBlockOffset, SizeDataBlock (o, nel caso di WNODE_SINGLE_ITEM, SizeDataItem) e VariableData. WNODE_METHOD_ITEM include un MethodIde WNODE_SINGLE_ITEM include un ItemId che WNODE_SINGLE_INSTANCE manca.

WNODE_ALL_DATA differisce dalle strutture precedenti in cui viene usato per passare più istanze di un blocco di dati, possibilmente inclusi nomi di istanza dinamici e possibilmente di dimensioni diverse.

La figura seguente mostra un diagramma a blocchi di un buffer IRP contenente un WNODE_ALL_DATA che un driver potrebbe restituire in risposta a una richiesta di IRP_MN_QUERY_ALL_DATA .

A partire dalla parte superiore della figura precedente:

• Come descritto nella figura precedente, la struttura WNODE_HEADER all'inizio della WNODE_ALL_DATA è contenuta in un membro WnodeHeader . WnodeHeader.Buffersize e WnodeHeader.Guid indicano rispettivamente le dimensioni del WNODE_ALL_DATA e il GUID del blocco dati.

  In questo esempio WMI imposta WnodeHeader.Flags per indicare che questa struttura è un WNODE_ALL_DATA e che il blocco di dati è stato registrato con nomi di istanza dinamici, ovvero WMI cancella WNODE_FLAG_STATIC_INSTANCE_NAMES e WNODE_FLAG_PDO_INSTANCE_NAMES. In output, il driver imposta WNODE_FLAG_FIXED_INSTANCE_SIZE per indicare che tutte le istanze sono le stesse dimensioni.

• WMI imposta DataBlockOffset per indicare l'offset dall'inizio del buffer al primo byte dei dati dell'istanza. Il driver non deve modificare questo valore. In questo esempio, i dati dell'istanza seguono i nomi di istanza in OffsetInstanceNameOffsets.

• Il driver imposta InstanceCount per indicare il numero di istanze restituite.

• WNODE_XXX per i blocchi di dati che usano nomi di istanza dinamici contengono sempre le stringhe del nome dell'istanza. Poiché in questo esempio vengono usati nomi di istanza dinamici, OffsetInstanceNameOffsets indica l'offset dall'inizio del buffer a una matrice di offset ai nomi di istanza dinamici nel buffer.

• FixedInstanceSize indica il numero di byte di dati in ogni istanza restituita dal driver. Se le istanze di questo blocco di dati variano in base alle dimensioni, il driver cancella WNODE_FLAG_FIXED_INSTANCE_SIZE in WnodeHeader.Flags e imposta OffsetInstanceDataAndLength su una matrice di strutture OFFSETINSTANCEDATAANDLENGTH , ognuna che specifica un offset per i dati per un'istanza e il numero di byte in tale istanza anziché impostare FixedInstanceSize.

Per altre informazioni sulle strutture WNODE_XXX , vedere Strutture di sistema.