Strutture WNODE_XXX WMI

WMI usa un set di strutture di dati standard denominate WNODE_XXX per passare 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 WNODE_strutture 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 percorso.

Nella tabella seguente sono elencati i provider di integrazione WMI e le struttureXXX corrispondenti WNODE_.

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

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

Ogni WNODE_struttura XXX è costituita dai seguenti elementi:

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

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

Una struttura diXXX WNODE_in un buffer IRP (Parameters.WMI.Buffer) è in genere seguita da dati variabili correlati alla richiesta, ad esempio nomi di istanza dinamica, stringhe dei nomi di istanza statici, 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 sizeof(WNODE_XXX) in base alla 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 su 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 a 2 byte.

La figura seguente illustra 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 del 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 del 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 le dimensioni del buffer allocato 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 è un 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 utilizzato.

• 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 in questo caso, poiché il blocco di dati usa nomi di istanza statici, questo offset indica la stessa posizione di VariableData. Se il blocco di dati usa nomi di istanza dinamici, i nomi di istanza iniziano in corrispondenza di VariableData e DataBlockOffset specificare 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 presenti), il driver scrive i dati dell'istanza per l'istanza richiesta nel buffer di output.

Un driver legge e scrive WNODE_METHOD_ITEM e WNODE_SINGLE_ITEM strutture in modo analogo a WNODE_SINGLE_INSTANCE. Queste strutture sono simili tra loro in quanto ognuno ha i membri fissi OffsetInstanceName, InstanceIndex, DataBlockOffset, SizeDataBlock (o, nel caso di WNODE_SINGLE_ITEM, SizeDataItem) e VariableData. WNODE_METHOD_ITEM include un MethodId e WNODE_SINGLE_ITEM include un ItemId che WNODE_SINGLE_INSTANCE manca.

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

La figura seguente illustra 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 del WNODE_ALL_DATA è contenuta in un membro WnodeHeader. WnodeHeader.Buffersize e WnodeHeader.Guid indicare rispettivamente le dimensioni del WNODE_ALL_DATA e il GUID del blocco di 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. Nell'output, il driver imposta WNODE_FLAG_FIXED_INSTANCE_SIZE per indicare che tutte le istanze hanno 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 utilizzati nomi di istanza dinamici, OffsetInstanceNameOffsets indica l'offset dall'inizio del buffer a una matrice di offset ai nomi delle istanze dinamiche 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, ognuno dei quali 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 System Structures.