WMI_FUNCTION_CONTROL_CALLBACK funzione di callback (wmilib.h)

Articolo
02/07/2025

La routine DpWmiFunctionControl abilita o disabilita la notifica degli eventi e abilita o disabilita la raccolta dei dati per i blocchi di dati registrati come costosi da raccogliere dal driver. 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 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 dei GUID forniti dal driver nella struttura WMILIB_CONTEXT passato 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 set di driver WMIREG_FLAG_EXPENSIVE in Flags della struttura WMIGUIDREGINFO usata per registrare il blocco.

[in] Enable

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

Valore restituito

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

Osservazioni

WMI chiama la 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 WmiFunctionControl membro 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 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 intermedia 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 visualizzabile a pagina.

Per altre informazioni sull'implementazione di questa routine, vedere Calling WmiSystemControl to Handle WMI IRPs.