WMI_FUNCTION_CONTROL_CALLBACK fonction de rappel (wmilib.h)

Article
02/27/2024

La routine DpWmiFunctionControl active ou désactive la notification des événements, et active ou désactive la collecte de données pour les blocs de données que le pilote inscrit comme coûteux à collecter. Cette routine est facultative.

Syntaxe

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

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

Paramètres

[in] DeviceObject

Pointeur vers la structure de DEVICE_OBJECT WDM du pilote.

[in] Irp

Pointeur vers l’IRP.

[in] GuidIndex

Spécifie le bloc de données en fournissant un index de base zéro dans la liste des GUID fournis par le pilote dans la structure WMILIB_CONTEXT qu’il a transmise à WmiSystemControl.

[in] Function

Spécifie ce qu’il faut activer ou désactiver. WmiEventControl indique un événement et WmiDataBlockControl indique la collecte de données pour un bloc qui a été inscrit comme coûteux à collecter (autrement dit, un bloc pour lequel le pilote défini WMIREG_FLAG_EXPENSIVE dans Indicateurs de la structure WMIGUIDREGINFO utilisée pour inscrire le bloc).

[in] Enable

Spécifie TRUE pour activer l’événement ou la collecte de données, ou FALSE pour le désactiver.

Valeur retournée

DpWmiFunctionControl retourne STATUS_SUCCESS ou une status d’erreur appropriée, par exemple :

Remarques

WMI appelle la routine DpWmiFunctionControl d’un pilote après que le pilote a appelé WmiSystemControl en réponse à l’une des demandes suivantes :

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

Si un pilote implémente une routine DpWmiFunctionControl , il doit placer l’adresse de la routine dans le membre WmiFunctionControl de la structure WMILIB_CONTEXT qu’il transmet à WmiSystemControl. Si un pilote n’implémente pas de routine DpWmiFunctionControl , il doit définir WmiFunctionControl sur NULL. Dans ce dernier cas, WMI retourne STATUS_SUCCESS à l’appelant.

Le pilote est responsable de la validation de tous les arguments d’entrée. Plus précisément, le pilote doit effectuer les opérations suivantes :

Vérifiez que la valeur GuidIndex est comprise entre zéro et GuidCount-1, en fonction du membre GuidCount de la structure WMILIB_CONTEXT .
Vérifiez que le pilote n’a pas marqué le bloc de données spécifié pour la suppression. Si le pilote a récemment spécifié l’indicateur WMIREG_FLAG_REMOVE_GUID dans une structure WMIGUIDREGINFO contenue dans une structure de WMILIB_CONTEXT , il est possible qu’une demande supplémentaire arrive avant la suppression.

Il n’est pas nécessaire pour le pilote de case activée si les événements ou la collecte de données sont déjà activés pour un bloc, car WMI envoie une seule demande d’activation lorsque le premier consommateur de données active le bloc et envoie une seule demande de désactivation lorsque le dernier consommateur de données désactive le bloc. WMI n’appelle pas DpWmiFunctionControl pour activer un bloc sans appel intermédiaire pour le désactiver.

Après avoir activé ou désactivé l’événement ou la collecte de données pour le bloc, le pilote appelle WmiCompleteRequest pour terminer la demande.

Cette routine peut être paginable.

Pour plus d’informations sur l’implémentation de cette routine, consultez Appel de WmiSystemControl pour gérer les IIP WMI.