IRP_MN_QUERY_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 demande de IRP_MN_QUERY_SINGLE_INSTANCE , WMI appelle à son tour la routine DpWmiQueryDataBlock de ce pilote.

Code majeur

IRP_MJ_SYSTEM_CONTROL

Date d’envoi

WMI envoie cette IRP pour interroger une seule instance d’un bloc de données donné.

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

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

Parameters.WMI.BufferSize indique la taille maximale de la mémoire tampon non paginé sur Parameters.WMI.Buffer, qui pointe vers une structure WNODE_SINGLE_INSTANCE qui identifie les instance à interroger.

Paramètres de sortie

Si le pilote gère les irps WMI en appelant WmiSystemControl, WMI remplit une structure WNODE_SINGLE_INSTANCE avec les données fournies par la routine DpWmiQueryDataBlock du pilote.

Sinon, le pilote remplit la structure WNODE_SINGLE_INSTANCE dans Parameters.WMI.Buffer comme suit :

Mises à jour WnodeHeader.BufferSize avec la taille, en octets, de la structure de WNODE_SINGLE_INSTANCE de sortie, y compris les données instance. Cette valeur doit inclure la longueur du nom de instance (rempli de sorte que les données instance commencent sur une limite de quatre mots), même si la classe interrogée a inscrit des noms statiques instance et que l’enregistreur de pilotes ne fournit pas explicitement le nom lors de la maintenance de cette IRP.
Définit SizeDataBlock sur la taille, en octets, des données instance. Si des noms de instance statiques sont utilisés, cette valeur ne doit pas inclure la taille du nom instance.
Écrit les données instance dans Parameters.WMI.Buffer à partir de DataBlockOffset. Le pilote ne doit pas modifier la valeur d’entrée de DataBlockOffset.

Si la mémoire tampon sur Parameters.WMI.Buffer est trop petite pour recevoir toutes les données, le pilote remplit la taille nécessaire dans une structure WNODE_TOO_SMALL dans 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.

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_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

En cas de réussite, un pilote définit Irp-IoStatus.Information> sur la valeur entrée dans WnodeHeader.BufferSize. Cette valeur inclut la longueur du nom de la instance statique.

Opération

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 gère les irps WMI en appelant WmiSystemControl, WmiSystemControl appelle la routine DpWmiQueryDataBlock du pilote.

Si un pilote gère lui-même une requête IRP_MN_QUERY_SINGLE_INSTANCE , il ne doit le faire que si Parameters.WMI.ProviderId pointe vers le même objet de périphérique que le pointeur que le pilote a passé dans son appel à IoWMIRegistrationControl. Sinon, le pilote doit transférer la demande au pilote inférieur suivant dans la pile de périphériques.

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.

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 Parameters.WMI.BufferSize spécifie une mémoire tampon suffisamment grande pour recevoir toutes les données que le pilote retournera.

Si le pilote prend en charge le bloc de données, il vérifie le WNODE_SINGLE_INSTANCE d’entrée 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 à 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 un USHORT, qui correspond à la longueur 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 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 une 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 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 remplit la structure WNODE_SINGLE_INSTANCE dans Parameters.WMI.Buffer avec les données pour le instance.

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