Condividi tramite


IRP_MN_EXECUTE_METHOD

Tutti i driver che supportano i metodi all'interno dei blocchi di dati 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_EXECUTE_METHOD , WMI a sua volta chiama la routine DpWmiExecuteMethod del driver.

Codice principale

IRP_MJ_SYSTEM_CONTROL

Data di invio

WMI invia questo IRP per eseguire un metodo associato a un blocco di dati.

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

WMI invierà 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.

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 associato al metodo da eseguire.

Parameters.WMI.BufferSize indica le dimensioni del buffer non di paging in Parameters.WMI.Buffer che deve essere >= sizeof(WNODE_METHOD_ITEM) più le dimensioni di tutti i dati di output per il metodo.

Parameters.WMI.Buffer punta a una struttura WNODE_METHOD_ITEM in cui MethodID indica l'identificatore del metodo da eseguire e DataBlockOffset indica l'offset in byte dall'inizio della struttura al primo byte dei dati di input, se presenti. Parameters.WMI.Buffer-> SizeDataBlock indica le dimensioni in byte dell'input WNODE_METHOD_ITEM inclusi i dati di input oppure zero se non è presente alcun input.

Parametri di output

Se il driver gestisce i runtime di integrazione WMI chiamando WmiSystemControl, WMI compila il WNODE_METHOD_ITEM con i dati restituiti dalla routine DpWmiExecuteMethod del driver.

In caso contrario, il driver compila la struttura WNODE_METHOD_ITEM a cui Parameters.WMI.Buffer punta come indicato di seguito:

  • Aggiornamenti WnodeHeader.BufferSize con le dimensioni del WNODE_METHOD_ITEM di output, inclusi i dati di output.

  • Aggiornamenti SizeDataBlock con le dimensioni dei dati di output o zero se non sono presenti dati di output.

  • Controlla Parameters.WMI.Buffersize per determinare se il buffer è sufficientemente grande da ricevere l'output WNODE_METHOD_ITEM inclusi i dati di output. Se il buffer non è sufficientemente grande, il driver riempie le dimensioni necessarie in una struttura WNODE_TOO_SMALL a cui punta Parameters.WMI.Buffer. Se il buffer è inferiore a sizeof(WNODE_TOO_SMALL), il driver ha esito negativo e restituisce STATUS_BUFFER_TOO_SMALL.

  • Scrive i dati di output, se presenti, sui dati di input a partire da DataBlockOffset. Il driver non deve modificare il valore di input di DataBlockOffset.

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

STATUS_WMI_ITEMID_NOT_FOUND

In caso di esito positivo, un driver imposta Irp-IoStatus.Information> sul numero di byte scritti nel buffer in Parameters.WMI.Buffer.

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, tale routine chiama la routine DpWmiExecuteMethod del driver oppure restituisce STATUS_INVALID_DEVICE_REQUEST se il driver non definisce la routine.

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

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_METHOD_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 identifichi un'istanza del blocco di dati supportata dal driver.

  • Verificare che il membro MethodId della struttura WNODE_METHOD_ITEM sia compreso nell'intervallo di identificatori di metodo supportati dal driver per il blocco di dati e che il chiamante sia autorizzato a eseguire il metodo.

  • Verificare che i membri DataBlockOffset e SizeDataBlock della struttura WNODE_METHOD_ITEM descrivono un buffer di dimensioni sufficienti per contenere i parametri del metodo specificato e che i parametri siano validi per il metodo.

  • Verificare che Parameters.WMI.Buffersize specifichi un buffer sufficientemente grande da ricevere la struttura WNODE_METHOD_ITEM dopo l'aggiornamento con i dati di output.

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

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.

Se il driver supporta il blocco di dati, controlla il WNODE_METHOD_ITEM 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_METHOD_ITEM di input. OffsetInstanceName è l'offset in byte dall'inizio della struttura a un USHORT che è 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.

Il driver controlla quindi l'ID del metodo nel WNODE_METHOD_ITEM di input per determinare se è un metodo valido per tale blocco di dati. In caso contrario, il driver non riesce l'IRP e restituisce STATUS_WMI_ITEMID_NOT_FOUND.

Se il metodo genera l'output, il driver deve controllare le dimensioni del buffer di output in Parameters.WMI.BufferSize prima di eseguire qualsiasi operazione che potrebbe avere effetti collaterali o che non devono essere eseguiti due volte. Ad esempio, se un metodo restituisce i valori di un gruppo di contatori e quindi reimposta i contatori, il driver deve controllare le dimensioni del buffer (e interrompere l'IRP se il buffer è troppo piccolo) prima di reimpostare i contatori. Ciò garantisce che WMI possa inviare di nuovo la richiesta in modo sicuro con un buffer più grande.

Se l'istanza e l'ID del metodo sono validi e la dimensione del buffer è adeguata, il driver esegue il metodo . Se SizeDataBlock nel WNODE_METHOD_ITEM di input è diverso da zero, il driver usa i dati a partire da DataBlockOffset come input per il metodo .

Se il metodo genera l'output, il driver scrive i dati di output nel buffer a partire da DataBlockOffset e imposta SizeDataBlock nell'output WNODE_METHOD_ITEM sul numero di byte di dati di output. Se il metodo non contiene dati di output, il driver imposta SizeDataBlock su zero. Il driver non deve modificare il valore di input di DataBlockOffset.

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

Requisiti

Intestazione

Wdm.h (include Wdm.h, Ntddk.h o Ntifs.h)

Vedi anche

DpWmiExecuteMethod

IoWMIRegistrationControl

WMILIB_CONTEXT

WmiSystemControl

WNODE_METHOD_ITEM