IRP_MN_EXECUTE_METHOD

Article
06/15/2023

Tous les pilotes qui prennent en charge les méthodes dans les blocs de données doivent gérer cette IRP. Un pilote peut gérer les IRP WMI en appelant WmiSystemControl ou en gérant l’IRP lui-même, comme décrit dans Gestion des demandes WMI.

Si un pilote appelle WmiSystemControl pour gérer une demande de IRP_MN_EXECUTE_METHOD , WMI appelle à son tour la routine DpWmiExecuteMethod du pilote.

Code majeur

IRP_MJ_SYSTEM_CONTROL

Date d’envoi

WMI envoie cette IRP pour exécuter une méthode associée à un bloc de données.

WMI envoie cette IRP à IRQL = PASSIVE_LEVEL dans un contexte de thread arbitraire.

WMI envoie un IRP_MN_QUERY_SINGLE_INSTANCE avant d’envoyer un IRP_MN_EXECUTE_METHOD. Si un pilote prend en charge IRP_MN_EXECUTE_METHOD il doit disposer d’un gestionnaire de IRP_MN_QUERY_SINGLE_INSTANCE pour le même bloc de données dont la méthode est en cours d’exécution.

Paramètres d’entrée

Parameters.WMI.ProviderId pointe vers l’objet de périphérique du pilote qui doit répondre à la demande. Ce pointeur se trouve à l’emplacement de la pile d’E/S du pilote dans l’IRP.

Parameters.WMI.DataPath pointe vers un GUID qui identifie le bloc de données associé à la méthode à exécuter.

Parameters.WMI.BufferSize indique la taille de la mémoire tampon non paginé dans Parameters.WMI.Buffer qui doit être >= sizeof(WNODE_METHOD_ITEM) plus la taille des données de sortie pour la méthode.

Parameters.WMI.Buffer pointe vers une structure WNODE_METHOD_ITEM dans laquelle MethodID indique l’identificateur de la méthode à exécuter et DataBlockOffset indique le décalage en octets entre le début de la structure et le premier octet de données d’entrée, le cas échéant. Parameters.WMI.Buffer-> SizeDataBlock indique la taille en octets de l’entrée WNODE_METHOD_ITEM y compris les données d’entrée, ou zéro s’il n’y a pas d’entrée.

Paramètres de sortie

Si le pilote gère les IIP WMI en appelant WmiSystemControl, WMI remplit le WNODE_METHOD_ITEM avec les données retournées par la routine DpWmiExecuteMethod du pilote.

Sinon, le pilote remplit la structure WNODE_METHOD_ITEM vers laquelle Parameters.WMI.Buffer pointe comme suit :

Mises à jour WnodeHeader.BufferSize avec la taille de la WNODE_METHOD_ITEM de sortie, y compris les données de sortie.
Mises à jour SizeDataBlock avec la taille des données de sortie, ou zéro s’il n’y a pas de données de sortie.
Vérifie Parameters.WMI.Buffersize pour déterminer si la mémoire tampon est suffisamment grande pour recevoir les WNODE_METHOD_ITEM de sortie, y compris les données de sortie. Si la mémoire tampon n’est pas assez grande, le pilote remplit la taille nécessaire dans une structure WNODE_TOO_SMALL pointée par Parameters.WMI.Buffer. Si la mémoire tampon est inférieure à sizeof(WNODE_TOO_SMALL), le pilote échoue à l’IRP et retourne STATUS_BUFFER_TOO_SMALL.
Écrit les données de sortie, le cas échéant, sur les données d’entrée à partir de DataBlockOffset. Le pilote ne doit pas modifier la valeur d’entrée de DataBlockOffset.

Bloc d’état E/S

Si le pilote gère l’IRP en appelant WmiSystemControl, WMI définit Irp-IoStatus.Status> et Irp-IoStatus.Information> dans le bloc d’E/S status.

Dans le cas contraire, le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou sur un status d’erreur approprié, par exemple :

STATUS_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_ITEMID_NOT_FOUND

En cas de réussite, un pilote définit Irp-IoStatus.Information> sur le nombre d’octets écrits dans la mémoire tampon sur Parameters.WMI.Buffer.

Opération

Un pilote peut gérer les IRP WMI en appelant WmiSystemControl ou en gérant l’IRP lui-même, comme décrit dans Gestion des demandes WMI.

Si un pilote gère les IIP WMI en appelant WmiSystemControl, cette routine appelle la routine DpWmiExecuteMethod du pilote ou retourne STATUS_INVALID_DEVICE_REQUEST si le pilote ne définit pas la routine.

Si un pilote gère lui-même une demande de IRP_MN_EXECUTE_METHOD , il doit le faire uniquement si Parameters.WMI.ProviderId pointe vers le même objet d’appareil que le pointeur que le pilote a passé à IoWMIRegistrationControl. Dans le cas contraire, le pilote doit transférer la demande au pilote inférieur suivant.

Le pilote est responsable de la validation de toutes les valeurs d’entrée. Plus précisément, le pilote doit effectuer les opérations suivantes s’il gère la requête IRP elle-même :

Pour les noms statiques, vérifiez que le membre InstanceIndex de la structure WNODE_METHOD_ITEM se trouve dans la plage des index instance pris en charge par le pilote pour le bloc de données.
Pour les noms dynamiques, vérifiez que la chaîne de nom instance identifie un bloc de données instance pris en charge par le pilote.
Vérifiez que le membre MethodId de la structure WNODE_METHOD_ITEM se trouve dans la plage d’identificateurs de méthode pris en charge par le pilote pour le bloc de données et que l’appelant est autorisé à exécuter la méthode.
Vérifiez que les membres DataBlockOffset et SizeDataBlock de la structure WNODE_METHOD_ITEM décrivent une mémoire tampon suffisamment grande pour contenir les paramètres de la méthode spécifiée, et que les paramètres sont valides pour la méthode.
Vérifiez que Parameters.WMI.Buffersize spécifie une mémoire tampon suffisamment grande pour recevoir la structure WNODE_METHOD_ITEM après sa mise à jour avec les données de sortie.

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

Avant de gérer la demande, le pilote doit déterminer si Parameters.WMI.DataPath pointe vers un GUID pris en charge par le pilote. Si ce n’est pas le cas, le pilote doit échouer l’IRP et retourner STATUS_WMI_GUID_NOT_FOUND.

Si le pilote prend en charge le bloc de données, il vérifie le WNODE_METHOD_ITEM d’entrée sur Parameters.WMI.Buffer pour le nom de instance, comme suit :

Si WNODE_FLAG_STATIC_INSTANCE_NAMES est défini dans WnodeHeader.Flags, le pilote utilise InstanceIndex comme index dans la liste des noms de instance statiques du pilote pour ce bloc. WMI obtient l’index à partir des données d’inscription fournies par le pilote lors de l’inscription du bloc.
Si WNODE_FLAG_STATIC_INSTANCE_NAMES est clair dans WnodeHeader.Flags, le pilote utilise le décalage sur OffsetInstanceName pour localiser la chaîne de nom instance dans le WNODE_METHOD_ITEM d’entrée. OffsetInstanceName est le décalage en octets entre le début de la structure et un USHORT qui correspond à la longueur de la chaîne de nom instance en octets (pas de caractères), y compris la valeur null de fin si présente, suivie de la chaîne de nom instance dans Unicode.

Si le pilote ne parvient pas à localiser le instance spécifié, il doit échouer l’IRP et retourner STATUS_WMI_INSTANCE_NOT_FOUND. Pour un instance avec un nom de instance dynamique, cette status indique que le pilote ne prend pas en charge le instance. WMI peut donc continuer à interroger d’autres fournisseurs de données et renvoyer une erreur appropriée au consommateur de données si un autre fournisseur trouve le instance mais ne peut pas gérer la demande pour une autre raison.

Le pilote vérifie ensuite l’ID de méthode dans le WNODE_METHOD_ITEM d’entrée pour déterminer s’il s’agit d’une méthode valide pour ce bloc de données. Si ce n’est pas le cas, le pilote échoue à l’IRP et retourne STATUS_WMI_ITEMID_NOT_FOUND.

Si la méthode génère une sortie, le pilote doit case activée la taille de la mémoire tampon de sortie dans Parameters.WMI.BufferSize avant d’effectuer une opération qui peut avoir des effets secondaires ou qui ne doit pas être effectuée deux fois. Par exemple, si une méthode retourne les valeurs d’un groupe de compteurs, puis réinitialise les compteurs, le pilote doit case activée la taille de la mémoire tampon (et échouer l’IRP si la mémoire tampon est trop petite) avant de réinitialiser les compteurs. Cela garantit que WMI peut renvoyer la demande en toute sécurité avec une mémoire tampon plus grande.

Si le instance et l’ID de méthode sont valides et que la mémoire tampon est de taille adéquate, le pilote exécute la méthode. Si SizeDataBlock dans le WNODE_METHOD_ITEM d’entrée est différent de zéro, le pilote utilise les données à partir de DataBlockOffset comme entrée pour la méthode.

Si la méthode génère une sortie, le pilote écrit les données de sortie dans la mémoire tampon à partir de DataBlockOffset et définit SizeDataBlock dans le WNODE_METHOD_ITEM de sortie sur le nombre d’octets de données de sortie. Si la méthode n’a pas de données de sortie, le pilote définit SizeDataBlock sur zéro. Le pilote ne doit pas modifier la valeur d’entrée de DataBlockOffset.

Si le instance est valide, mais que le pilote ne peut pas gérer la demande, il peut retourner les status d’erreur appropriées.