IRP_MN_CHANGE_SINGLE_ITEM

Article
06/15/2023

Tous les pilotes qui prennent en charge WMI 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_CHANGE_SINGLE_ITEM , WMI appelle à son tour la routine DpWmiSetDataItem de ce pilote.

Code majeur

IRP_MJ_SYSTEM_CONTROL

Date d’envoi

WMI envoie cette IRP pour modifier un seul élément de données dans un seul instance d’un bloc de données.

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

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 à définir.

Parameters.WMI.BufferSize indique la taille de la mémoire tampon non paginé sur Parameters.WMI.Buffer.

Parameters.WMI.Buffer, pointe vers une structure WNODE_SINGLE_ITEM qui identifie la instance du bloc de données, l’ID de l’élément à définir et une nouvelle valeur de données.

Paramètres de sortie

Aucun.

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_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_ITEMID_NOT_FOUND

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

En cas de réussite, un pilote définit Irp-IoStatus.Information> sur zéro.

Opération

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

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

N’implémentez pas la prise en charge de IRP_MN_CHANGE_SINGLE_ITEM , sauf si vous êtes sûr qu’un composant en mode utilisateur fourni par le système nécessite cette fonctionnalité.

Avant de gérer une requête, 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 doit case activée la structure d’entrée WNODE_SINGLE_ITEM vers laquelle Parameters.WMI.Buffer pointe pour le nom 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 la structure de WNODE_SINGLE_ITEM d’entrée. OffsetInstanceName est le décalage en octets entre le début de la structure et une longueur USHORT de la chaîne de nom instance en octets (pas de caractères). Cette longueur inclut le terminateur NULL le cas échéant, suivi de la chaîne de nom instance en Unicode.

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_SINGLE_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 ItemId de la structure WNODE_SINGLE_ITEM se trouve dans la plage d’identificateurs d’élément pris en charge par le pilote pour le bloc de données.
Vérifiez que les membres DataBlockOffset et SizeDataItem de la structure WNODE_SINGLE_ITEM décrivent un bloc de données de taille valide et que le contenu de la mémoire tampon est valide pour l’élément de données.
Vérifiez que l’élément de données spécifié est celui pour lequel le pilote autorise les modifications initiées par l’appelant. En d’autres termes, le pilote ne doit pas autoriser les modifications des éléments de données que vous envisagez d’être en lecture seule.

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

Si le pilote localise le instance et peut gérer la requête, il définit l’élément de données dans le instance sur la valeur dans le WNODE_SINGLE_ITEM. Si l’élément de données est en lecture seule, le pilote laisse l’élément inchangé, échoue à l’IRP et retourne STATUS_WMI_READ_ONLY.

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.