IRP_MN_CHANGE_SINGLE_ITEM

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_ITEM , WMI chiama a sua volta la routine DpWmiSetDataItem del driver.

Codice principale

IRP_MJ_SYSTEM_CONTROL

Data di invio

WMI invia l'IRP per modificare un singolo elemento 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 I/O del driver in IRP.

Parameters.WMI.DataPath punta a un GUID che identifica il blocco di dati da impostare.

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

Parameters.WMI.Buffer, punta a una struttura WNODE_SINGLE_ITEM che identifica l'istanza del blocco di dati, l'ID dell'elemento da impostare e un nuovo valore 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 di I/O.

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

STATUS_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_ITEMID_NOT_FOUND

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

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

Operazione

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

Se un driver gestisce IRP_MN_CHANGE_SINGLE_ITEM richieste, deve farlo solo se Parameters.WMI.ProviderId punta allo stesso oggetto dispositivo del puntatore passato al driver IoWMIRegistrationControl. In caso contrario, il driver deve inoltrare la richiesta al driver inferiore successivo.

Non implementare il supporto per IRP_MN_CHANGE_SINGLE_ITEM a meno che non si sia certi che un componente in modalità utente fornito dal sistema richieda questa funzionalità.

Prima di gestire una 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.

Se il driver supporta il blocco di dati, deve controllare la struttura di input WNODE_SINGLE_ITEM a cui Parameters.WMI.Buffer punta 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 di nomi di istanze statiche 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 nella struttura di input WNODE_SINGLE_ITEM . 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). Questa lunghezza include il terminatore NULL se presente, seguito dalla stringa 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_ITEM 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 identifica un'istanza del blocco di dati supportata dal driver.
Verificare che il membro ItemId della struttura WNODE_SINGLE_ITEM sia compreso nell'intervallo di identificatori di elemento supportati dal driver per il blocco dati.
Verificare che i membri DataBlockOffset e SizeDataItem della struttura WNODE_SINGLE_ITEM descrivono un blocco di dati di dimensioni valide e che il contenuto del buffer sia valido per l'elemento dati.
Verificare che l'elemento di dati specificato sia uno per cui il driver consente modifiche avviate dal chiamante. In altre parole, il driver non deve consentire modifiche agli elementi di dati che si intende essere di sola lettura.

Non presupporre che il contesto del thread sia quello dell'applicazione in modalità utente che avvia, un driver di livello superiore potrebbe essere stato modificato.

Se il driver non riesce a individuare l'istanza specificata, deve avere esito negativo sull'IRP 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, imposta l'elemento di dati nell'istanza del valore nella WNODE_SINGLE_ITEM. Se l'elemento di dati è di sola lettura, il driver lascia invariato l'elemento, ha esito negativo e restituisce STATUS_WMI_READ_ONLY.

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