IRP_MN_QUERY_SINGLE_INSTANCE

Articolo
06/15/2023

Tutti i driver che supportano WMI devono gestire questo IRP. Un driver può gestire i provider di integrazione WMI chiamando WmiSystemControl o gestendo l'IRP stesso, come descritto in Gestione delle richieste WMI.

Se un driver chiama WmiSystemControl per gestire una richiesta di IRP_MN_QUERY_SINGLE_INSTANCE , WMI a sua volta chiama la routine DpWmiQueryDataBlock del driver.

Codice principale

IRP_MJ_SYSTEM_CONTROL

Data di invio

WMI invia questo IRP per eseguire una query per una singola istanza di un determinato blocco di dati.

WMI invia un IRP_MN_QUERY_SINGLE_INSTANCE prima di inviare un IRP_MN_EXECUTE_METHOD. Se un driver supporta IRP_MN_EXECUTE_METHOD, deve avere un gestore IRP_MN_QUERY_SINGLE_INSTANCE per lo stesso blocco di dati il cui metodo viene eseguito.

WMI invia questo IRP in IRQL = PASSIVE_LEVEL in un contesto di thread arbitrario.

Parametri di input

Parameters.WMI.ProviderId punta all'oggetto dispositivo del driver che deve rispondere alla richiesta. Questo puntatore si trova nella posizione dello stack di I/O del driver nell'IRP.

Parameters.WMI.DataPath punta a un GUID che identifica il blocco di dati da eseguire per la query.

Parameters.WMI.BufferSize indica le dimensioni massime del buffer non di paging in Parameters.WMI.Buffer, che punta a una struttura WNODE_SINGLE_INSTANCE che identifica l'istanza di cui eseguire la query.

Parametri di output

Se il driver gestisce i runtime di integrazione WMI chiamando WmiSystemControl, WMI compila una struttura WNODE_SINGLE_INSTANCE con i dati forniti dalla routine DpWmiQueryDataBlock del driver.

In caso contrario, il driver compila la struttura WNODE_SINGLE_INSTANCE in Parameters.WMI.Buffer come indicato di seguito:

Aggiornamenti WnodeHeader.BufferSize con le dimensioni, in byte, della struttura di WNODE_SINGLE_INSTANCE di output, inclusi i dati dell'istanza. Questo valore deve includere la lunghezza del nome dell'istanza (riempito in modo che i dati dell'istanza inizino su un limite di parole quad), anche se la classe su cui viene eseguita una query sui nomi di istanza statici registrati e il writer di driver non specifica in modo esplicito il nome durante la manutenzione di questo provider di risorse.
Imposta SizeDataBlock sulle dimensioni, in byte, dei dati dell'istanza. Se i nomi di istanza statici sono in uso, questo valore non deve includere le dimensioni del nome dell'istanza.
Scrive i dati dell'istanza in Parameters.WMI.Buffer a partire da DataBlockOffset. Il driver non deve modificare il valore di input di DataBlockOffset.

Se il buffer in Parameters.WMI.Buffer è troppo piccolo per ricevere tutti i dati, il driver inserisce le dimensioni necessarie in una struttura WNODE_TOO_SMALL in Parameters.WMI.Buffer. Se il buffer è inferiore a sizeof(WNODE_TOO_SMALL), il driver ha esito negativo e restituisce STATUS_BUFFER_TOO_SMALL.

Blocco dello stato I/O

Se il driver gestisce l'IRP chiamando WmiSystemControl, WMI imposta Irp-IoStatus.Status> e Irp-IoStatus.Information> nel blocco di stato I/O.

In caso contrario, il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o su uno stato di errore appropriato, ad esempio:

STATUS_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

In caso di esito positivo, un driver imposta Irp-IoStatus.Information> sul valore immesso in WnodeHeader.BufferSize. Questo valore include la lunghezza del nome dell'istanza statica.

Operazione

Un driver può gestire i provider di integrazione WMI chiamando WmiSystemControl o gestendo l'IRP stesso, come descritto in Gestione delle richieste WMI.

Se un driver gestisce i runtime di integrazione WMI chiamando WmiSystemControl, WmiSystemControl chiama la routine DpWmiQueryDataBlock del driver.

Se un driver gestisce una richiesta IRP_MN_QUERY_SINGLE_INSTANCE stessa, deve farlo solo se Parameters.WMI.ProviderId punta allo stesso oggetto dispositivo del puntatore che il driver ha passato nella chiamata a IoWMIRegistrationControl. In caso contrario, il driver deve inoltrare la richiesta al driver inferiore successivo nello stack di dispositivi.

Prima di gestire la richiesta, il driver deve determinare se Parameters.WMI.DataPath punta a un GUID supportato dal driver. In caso contrario, il driver deve avere esito negativo sull'IRP e restituire STATUS_WMI_GUID_NOT_FOUND.

Il driver è responsabile della convalida di tutti i valori di input. In particolare, il driver deve eseguire le operazioni seguenti se gestisce la richiesta IRP stessa:

Per i nomi statici, verificare che il membro InstanceIndex della struttura WNODE_SINGLE_INSTANCE sia compreso nell'intervallo di indici di istanza supportati dal driver per il blocco di dati.
Per i nomi dinamici, verificare che la stringa del nome dell'istanza identifichi un'istanza del blocco di dati supportata dal driver.
Verificare che Parameters.WMI.BufferSize specifichi un buffer sufficientemente grande da ricevere tutti i dati restituiti dal driver.

Se il driver supporta il blocco di dati, controlla il WNODE_SINGLE_INSTANCE di input in Parameters.WMI.Buffer per il nome dell'istanza, come indicato di seguito:

Se WNODE_FLAG_STATIC_INSTANCE_NAMES è impostato in WnodeHeader.Flags, il driver usa InstanceIndex come indice nell'elenco dei nomi di istanza statici del driver per tale blocco. WMI ottiene l'indice dai dati di registrazione forniti dal driver quando ha registrato il blocco.
Se WNODE_FLAG_STATIC_INSTANCE_NAMES è chiaro in WnodeHeader.Flags, il driver usa l'offset in OffsetInstanceName per individuare la stringa del nome dell'istanza nel WNODE_SINGLE_INSTANCE di input. OffsetInstanceName è l'offset, espresso in byte, dall'inizio della struttura a USHORT, ovvero la lunghezza della stringa del nome dell'istanza in byte (non caratteri), incluso il valore Null di terminazione, se presente, seguito dalla stringa del nome dell'istanza in Unicode.

Se il driver non riesce a individuare l'istanza specificata, deve avere esito negativo e restituire STATUS_WMI_INSTANCE_NOT_FOUND. Per un'istanza con un nome di istanza dinamica, questo stato indica che il driver non supporta l'istanza. WMI può quindi continuare a eseguire query su altri provider di dati e restituire un errore appropriato al consumer di dati se un altro provider trova l'istanza, ma non può gestire la richiesta per un altro motivo.

Se il driver individua l'istanza e può gestire la richiesta, compila la struttura WNODE_SINGLE_INSTANCE in Parameters.WMI.Buffer con i dati per l'istanza.

Se l'istanza è valida, ma il driver non può gestire la richiesta, può restituire qualsiasi stato di errore appropriato.