WMI_EXECUTE_METHOD_CALLBACK fonction de rappel (wmilib.h)

Article
03/05/2024

La routine DpWmiExecuteMethod exécute une méthode associée à un bloc de données. Cette routine est facultative.

Syntaxe

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
)
{...}

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] InstanceIndex

Si le bloc spécifié par GuidIndex comporte plusieurs instances, InstanceIndex spécifie une valeur d’index de base zéro qui identifie le instance.

[in] MethodId

Spécifie l’ID de la méthode à exécuter. Le pilote définit l’ID de méthode en tant qu’élément dans un bloc de données.

[in] InBufferSize

Indique la taille en octets des données d’entrée. S’il n’existe aucune donnée d’entrée, InBufferSize est égal à zéro.

[in] OutBufferSize

Indique le nombre d’octets disponibles dans la mémoire tampon pour les données de sortie.

[in, out] Buffer

Pointeur vers une mémoire tampon qui contient les données d’entrée, le cas échéant, et reçoit les données de sortie, le cas échéant, pour la méthode. Si la mémoire tampon est trop petite pour recevoir toutes les données de sortie, le pilote retourne STATUS_BUFFER_TOO_SMALL et appelle WmiCompleteRequest avec la taille requise.

Valeur retournée

DpWmiExecuteMethod retourne STATUS_SUCCESS ou un code d’erreur approprié comme le suivant :

Remarques

WMI appelle la routine DpWmiExecuteMethod d’un pilote après que le pilote a appelé WmiSystemControl en réponse à une demande de IRP_MN_EXECUTE_METHOD .

Si un pilote implémente une routine DpWmiExecuteMethod , il doit placer l’adresse de la routine dans le membre ExecuteWmiMethod de la structure WMILIB_CONTEXT qu’il transmet à WmiSystemControl. Si un pilote n’implémente pas une routine DpWmiExecuteMethod , il doit définir ExecuteWmiMethod sur NULL. Dans ce dernier cas, WMI retourne STATUS_INVALID_DEVICE_REQUEST à l’appelant en réponse à une demande IRP_MN_EXECUTE_METHOD .

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.
Vérifiez que la valeur InstanceIndex se trouve dans la plage des index instance pris en charge par le pilote pour le bloc de données.
Vérifiez que l’identificateur de méthode fourni par MethodId est un identificateur valide pour le bloc de données spécifié et que l’appelant est autorisé à exécuter la méthode.
Vérifiez que Buffer et InBufferSize décrivent une mémoire tampon suffisamment grande pour contenir les paramètres d’entrée de la méthode spécifiée, y compris le remplissage si nécessaire, et vérifiez que les paramètres d’entrée sont valides.
Vérifiez que Buffer et OutBufferSize décrivent une mémoire tampon suffisamment grande pour recevoir les données de sortie de la méthode spécifiée, y compris le remplissage si nécessaire.

Ne partez pas du principe que le contexte de thread est celui de l’application en mode utilisateur de lancement. Un pilote de niveau supérieur peut l’avoir modifié.

Si la méthode spécifiée effectue une opération qui provoque une perte de données, telle que l’extraction et la réinitialisation du contenu d’un ensemble de compteurs, le pilote doit valider la taille de la mémoire tampon de sortie avant d’effectuer l’opération. De cette façon, le pilote peut retourner STATUS_BUFFER_TOO_SMALL et autoriser l’appelant à soumettre à nouveau la requête avec une mémoire tampon plus grande, sans réinitialiser prématurément les compteurs.

Après avoir exécuté la méthode et écrit toutes les données de sortie dans la mémoire tampon, 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.