IRP_MN_CHANGE_SINGLE_INSTANCE

Article
06/15/2023

Tous les pilotes qui prennent en charge WMI doivent gérer cette IRP. Un pilote peut gérer les irps 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 requête IRP_MN_CHANGE_SINGLE_INSTANCE , WMI appelle à son tour la routine DpWmiSetDataBlock de ce pilote.

Code majeur

IRP_MJ_SYSTEM_CONTROL

Date d’envoi

WMI envoie cette IRP pour modifier tous les éléments 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 associé au instance à modifier.

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

Parameters.WMI.Buffer pointe vers une structure de WNODE_SINGLE_INSTANCE qui identifie le instance et spécifie de nouvelles valeurs 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.

Sinon, le pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou sur une erreur appropriée status comme suit :

STATUS_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

En cas de réussite, le 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 DpWmiSetDataBlock du pilote ou retourne STATUS_WMI_READ_ONLY si le pilote ne définit pas la routine.

Si un pilote gère lui-même une demande de IRP_MN_CHANGE_SINGLE_INSTANCE , il le fait uniquement si le pointeur d’objet de périphérique sur Parameters.WMI.ProviderId correspond au pointeur transmis par le pilote dans son appel à IoWMIRegistrationControl. Sinon, le pilote doit transférer la demande au pilote inférieur suivant.

Si le pilote gère la requête, il doit d’abord case activée le GUID sur Parameters.WMI.DataPath pour déterminer s’il identifie un bloc de données 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 de WNODE_SINGLE_INSTANCE reçue sur Parameters.WMI.Buffer 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 le WNODE_SINGLE_INSTANCE d’entrée. OffsetInstanceName est le décalage en octets entre le début de la structure et une longueur de taille USHORT de la chaîne de nom instance en octets (et non en caractères), y compris la valeur null de fin si elle est présente, suivie de la chaîne de nom instance en Unicode.

Le pilote est chargé de valider 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_INSTANCE se trouve dans la plage d’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 les membres DataBlockOffset et SizeDataBlock de la structure WNODE_SINGLE_INSTANCE décrivent un bloc de données de taille valide, y compris tout remplissage existant entre les éléments de données, et que le contenu de la mémoire tampon est valide pour le bloc de données.
Vérifiez que le bloc de données spécifié est un bloc pour lequel le pilote autorise les modifications initiées par l’appelant. En d’autres termes, le pilote ne doit pas autoriser les modifications apportées aux blocs de données que vous aviez l’intention d’être en lecture seule.

Ne partez pas du principe que le contexte du 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. Si le instance a 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 retourner 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 les éléments de données accessibles en écriture dans le instance sur les valeurs de la structure WNODE_SINGLE_INSTANCE, ce qui laisse les éléments en lecture seule inchangés. Si l’intégralité du bloc de données est en lecture seule, le pilote doit échouer l’IRP et retourner STATUS_WMI_READ_ONLY.

Si le instance est valide mais que le pilote ne peut pas gérer la demande, il peut retourner toute erreur appropriée status.