WMI_EXECUTE_METHOD_CALLBACK funzione di callback (wmilib.h)

Articolo
03/05/2024

La routine DpWmiExecuteMethod esegue un metodo associato a un blocco di dati. Questa routine è facoltativa.

Sintassi

WMI_EXECUTE_METHOD_CALLBACK WmiExecuteMethodCallback;

NTSTATUS WmiExecuteMethodCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG MethodId,
  [in]      ULONG InBufferSize,
  [in]      ULONG OutBufferSize,
  [in, out] PUCHAR Buffer
)
{...}

Parametri

[in] DeviceObject

Puntatore alla struttura di DEVICE_OBJECT WDM del driver.

[in] Irp

Puntatore all'IRP.

[in] GuidIndex

Specifica il blocco di dati specificando un indice in base zero nell'elenco di GUID forniti dal driver nella struttura WMILIB_CONTEXT passata a WmiSystemControl.

[in] InstanceIndex

Se il blocco specificato da GuidIndex ha più istanze, InstanceIndex specifica un valore di indice in base zero che identifica l'istanza.

[in] MethodId

Specifica l'ID del metodo da eseguire. Il driver definisce l'ID del metodo come elemento in un blocco di dati.

[in] InBufferSize

Indica le dimensioni in byte dei dati di input. Se non sono presenti dati di input, InBufferSize è zero.

[in] OutBufferSize

Indica il numero di byte disponibili nel buffer per i dati di output.

[in, out] Buffer

Puntatore a un buffer che contiene i dati di input, se presenti, e riceve i dati di output, se presenti, per il metodo . Se il buffer è troppo piccolo per ricevere tutti i dati di output, il driver restituisce STATUS_BUFFER_TOO_SMALL e chiama WmiCompleteRequest con le dimensioni necessarie.

Valore restituito

DpWmiExecuteMethod restituisce STATUS_SUCCESS o un codice di errore appropriato, ad esempio:

Commenti

WMI chiama la routine DpWmiExecuteMethod di un driver dopo che il driver chiama WmiSystemControl in risposta a una richiesta di IRP_MN_EXECUTE_METHOD .

Se un driver implementa una routine DpWmiExecuteMethod , il driver deve inserire l'indirizzo della routine nel membro ExecuteWmiMethod della struttura WMILIB_CONTEXT che passa a WmiSystemControl. Se un driver non implementa una routine DpWmiExecuteMethod , deve impostare ExecuteWmiMethod su NULL. Nel secondo caso, WMI restituisce STATUS_INVALID_DEVICE_REQUEST al chiamante in risposta a qualsiasi richiesta di IRP_MN_EXECUTE_METHOD .

Il driver è responsabile della convalida di tutti gli argomenti di input. In particolare, il driver deve eseguire le operazioni seguenti:

Verificare che il valore GuidIndex sia compreso tra zero e GuidCount-1, in base al membro GuidCount della struttura WMILIB_CONTEXT .
Verificare che il driver non abbia contrassegnato il blocco di dati specificato per la rimozione. Se il driver ha specificato di recente il flag WMIREG_FLAG_REMOVE_GUID in una struttura WMIGUIDREGINFO contenuta in una struttura WMILIB_CONTEXT , è possibile che venga inviata una richiesta aggiuntiva prima che si verifichi la rimozione.
Verificare che il valore InstanceIndex sia compreso nell'intervallo di indici di istanza supportati dal driver per il blocco di dati.
Verificare che l'identificatore del metodo fornito da MethodId sia un identificatore valido per il blocco di dati specificato e che il chiamante sia autorizzato a eseguire il metodo.
Verificare che Buffer e InBufferSize descrivono un buffer sufficientemente grande da contenere i parametri di input del metodo specificato, inclusa la spaziatura interna, se necessario, e verificare che i parametri di input siano validi.
Verificare che Buffer e OutBufferSize descrivono un buffer di dimensioni sufficienti per ricevere i dati di output del metodo specificato, inclusa la spaziatura interna, se necessario.

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 metodo specificato esegue un'operazione che causa la perdita di dati, ad esempio il recupero e la reimpostazione del contenuto di un set di contatori, il driver deve convalidare le dimensioni del buffer di output prima di eseguire l'operazione. In questo modo, il driver può restituire STATUS_BUFFER_TOO_SMALL e consentire al chiamante di inviare di nuovo la richiesta con un buffer più grande, senza reimpostare prematuramente i contatori.

Dopo aver eseguito il metodo e aver scritto i dati di output nel buffer, il driver chiama WmiCompleteRequest per completare la richiesta.

Questa routine può essere paginabile.

Per altre informazioni sull'implementazione di questa routine, vedere Chiamata di WmiSystemControl per gestire i runtime di integrazione WMI.