fonction de rappel WMI_FUNCTION_CONTROL_CALLBACK (wmilib.h)

Article
02/07/2025

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 enregistrés par le pilote 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 fourni dans la structure WMILIB_CONTEXT passée à 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 d’un bloc inscrit comme coûteux à collecter (autrement dit, un bloc pour lequel le pilote a 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 FAUX pour le désactiver.

Valeur de retour

DpWmiFunctionControl retourne STATUS_SUCCESS ou un état d’erreur approprié, par exemple :

Remarques

WMI appelle la routine DpWmiFunctionControl d’un pilote après que le pilote appelle WmiSystemControl en réponse à l’une des requêtes 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, le pilote doit placer l’adresse de la routine dans le membre WmiFunctionControl de la structure WMILIB_CONTEXT qu’elle 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 chargé de valider 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 de WMIREG_FLAG_REMOVE_GUID dans un WMIGUIDREGINFO structure contenue dans une structure WMILIB_CONTEXT, il est possible qu’une demande supplémentaire arrive avant la suppression.

Il n’est pas nécessaire pour le pilote de vérifier si les événements ou la collecte de données sont déjà activés pour un bloc, car WMI envoie une demande d’activation unique lorsque le premier consommateur de données active le bloc et envoie une demande de désactivation unique 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 requête.

Cette routine peut être paginable.

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