WMI_FUNCTION_CONTROL_CALLBACK funzione di callback (wmilib.h)

Articolo
02/27/2024

La routine DpWmiFunctionControl consente o disabilita la notifica degli eventi e abilita o disabilita la raccolta dati per blocchi di dati registrati come costosi da raccogliere. Questa routine è facoltativa.

Sintassi

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

NTSTATUS WmiFunctionControlCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] WMIENABLEDISABLECONTROL Function,
  [in] BOOLEAN Enable
)
{...}

Parametri

[in] DeviceObject

Puntatore alla struttura WDM del driver DEVICE_OBJECT.

[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] Function

Specifica cosa abilitare o disabilitare. WmiEventControl indica un evento e WmiDataBlockControl indica la raccolta di dati per un blocco registrato come costoso da raccogliere, ovvero un blocco per cui il driver impostato WMIREG_FLAG_EXPENSIVE in Flag della struttura WMIGUIDREGINFO usata per registrare il blocco.

[in] Enable

Specifica TRUE per abilitare l'evento o la raccolta dati o FALSE per disabilitarla.

Valore restituito

DpWmiFunctionControl restituisce STATUS_SUCCESS o uno stato di errore appropriato, ad esempio:

Commenti

WMI chiama una routine DpWmiFunctionControl di un driver dopo che il driver chiama WmiSystemControl in risposta a una delle richieste seguenti:

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

Se un driver implementa una routine DpWmiFunctionControl , il driver deve inserire l'indirizzo della routine nel membro WmiFunctionControl della struttura WMILIB_CONTEXT che passa a WmiSystemControl. Se un driver non implementa una routine DpWmiFunctionControl , deve impostare WmiFunctionControl su NULL. In quest'ultimo caso, WMI restituisce STATUS_SUCCESS al chiamante.

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 di 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.

Non è necessario che il driver verifichi se gli eventi o la raccolta dati sono già abilitati per un blocco, perché WMI invia una singola richiesta di abilitazione quando il primo consumer di dati abilita il blocco e invia una singola richiesta di disabilitazione quando l'ultimo consumer di dati disabilita il blocco. WMI non chiamerà DpWmiFunctionControl per abilitare un blocco senza una chiamata di intervento per disabilitarla.

Dopo aver abilitato o disabilitato l'evento o la raccolta dati per il blocco, 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 provider di accesso WMI.