IRP_MN_CHANGE_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_CHANGE_SINGLE_INSTANCE , WMI a sua volta chiama la routine DpWmiSetDataBlock del driver.

Codice principale

IRP_MJ_SYSTEM_CONTROL

Data di invio

WMI invia questo IRP per modificare tutti gli elementi di dati in una singola istanza di un blocco di dati.

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 in IRP.

Parameters.WMI.DataPath punta a un GUID che identifica il blocco di dati associato all'istanza da modificare.

Parameters.WMI.BufferSize indica le dimensioni del buffer non di paging in Parameters.WMI.Buffer.

Parameters.WMI.Buffer punta a una struttura WNODE_SINGLE_INSTANCE che identifica l'istanza e specifica nuovi valori di dati.

Parametri di output

Nessuno.

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_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

In caso di esito positivo, il driver imposta Irp-IoStatus.Information> su zero.

Operazione

Se un driver gestisce i runtime di integrazione WMI chiamando WmiSystemControl, tale routine chiama la routine DpWmiSetDataBlock del driver o restituisce STATUS_WMI_READ_ONLY se il driver non definisce la routine.

Se un driver gestisce una richiesta IRP_MN_CHANGE_SINGLE_INSTANCE stessa, lo fa solo se il puntatore all'oggetto del dispositivo in Parameters.WMI.ProviderId corrisponde al puntatore passato dal driver nella chiamata a IoWMIRegistrationControl. In caso contrario, il driver deve inoltrare la richiesta al driver inferiore successivo.

Se il driver gestisce la richiesta, deve prima controllare il GUID in Parameters.WMI.DataPath per determinare se identifica un blocco di dati supportato dal driver. In caso contrario, il driver deve avere esito negativo sull'IRP e restituire STATUS_WMI_GUID_NOT_FOUND.

Se il driver supporta il blocco di dati, deve controllare la struttura WNODE_SINGLE_INSTANCE ricevuta 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 è deselezionata 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 in byte dall'inizio della struttura a una lunghezza di dimensioni USHORT 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.

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 i membri DataBlockOffset e SizeDataBlock della struttura WNODE_SINGLE_INSTANCE descrivano un blocco di dati di dimensioni valide, incluse eventuali spaziatura interna tra gli elementi di dati e che il contenuto del buffer sia valido per il blocco di dati.
Verificare che il blocco di dati specificato sia quello per il quale il driver consente modifiche avviate dal chiamante. In altre parole, il driver non deve consentire modifiche ai blocchi di dati che devono essere di sola lettura.

Non presupporre che il contesto del thread sia quello dell'applicazione in modalità utente di avvio. Un driver di livello superiore potrebbe averlo modificato.

Se il driver non riesce a individuare l'istanza specificata, deve avere esito negativo e restituire STATUS_WMI_INSTANCE_NOT_FOUND. Se l'istanza ha 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, imposta gli elementi di dati scrivibili nell'istanza sui valori nella struttura WNODE_SINGLE_INSTANCE , lasciando invariati tutti gli elementi di sola lettura. Se l'intero blocco di dati è di sola lettura, il driver deve interrompere l'IRP e restituire STATUS_WMI_READ_ONLY.

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