IRP_MN_QUERY_DEVICE_RELATIONS
Le gestionnaire PnP envoie cette demande pour déterminer certaines relations entre les appareils. Les types de pilotes suivants gèrent cette requête :
Les pilotes de bus doivent gérer BusRelations demandes pour leur adaptateur ou contrôleur (FDO bus). Les pilotes de filtre peuvent gérer les requêtes BusRelations.
Les pilotes bus doivent gérer TargetDeviceRelation demandes pour leurs appareils enfants (PDP enfants).
Les pilotes de fonction et de filtre peuvent gérer les requêtes RemovalRelations et PowerRelations.
Les pilotes de bus peuvent gérer EjectionRelations demandes pour leurs appareils enfants (PDP enfants).
Valeur
0x07
Code principal
Lorsqu’il est envoyé
Le gestionnaire PnP envoie cet IRP pour collecter des informations sur les appareils avec une relation avec l’appareil spécifié.
Le gestionnaire PnP interroge les BusRelations d’un appareil lorsque l’appareil est énuméré et à d’autres moments pendant qu’il est actif, par exemple lorsqu’un pilote appelle les IoInvalidateDeviceRelations routine pour indiquer qu’un appareil enfant est arrivé ou quitté.
Le gestionnaire PnP interroge les RemoveRelations d’un appareil avant de supprimer les pilotes d’un appareil. Le gestionnaire PnP interroge et ejectionRelations avant d’éjecter un appareil.
Le gestionnaire PnP interroge le TargetDeviceRelation d’un appareil lorsqu’une application en mode pilote ou en mode utilisateur s’inscrit pour la notification PnP d’une EventCategoryTargetDeviceChange sur l’appareil. Le gestionnaire PnP interroge l’appareil associé à un objet de fichier particulier. IRP_MN_QUERY_DEVICE_RELATIONS est le seul IRP PnP qui a un paramètre d’objet de fichier valide. Un pilote peut interroger une pile d’appareils pour TargetDeviceRelation. Un pilote n’a pas besoin de fournir un objet de fichier lors de l’envoi de son TargetDeviceRelation requête.
Le gestionnaire PnP interroge les PowerRelations d’un appareil lorsque le pilote de l’appareil appelle IoInvalidateDeviceRelations pour indiquer que l’ensemble des appareils avec lesquels cet appareil a une relation de gestion de l’alimentation implicite a changé. demandes de PowerRelations sont prises en charge à partir de Windows 7.
Pour BusRelations, RemovalRelations, EjectionRelationset demandes de PowerRelations, le gestionnaire PnP envoie IRP_MN_QUERY_DEVICE_RELATIONS au niveau irQL = PASSIVE_LEVEL dans le contexte d’un thread système.
Pour requêtes targetDeviceRelation, le gestionnaire PnP envoie ce protocole IRP à IRQL = PASSIVE_LEVEL dans un contexte de thread arbitraire.
Paramètres d’entrée
Le Parameters.QueryDeviceRelations.Type membre de la structure IO_STACK_LOCATION spécifie le type de relations interrogées. Les valeurs possibles incluent BusRelations, EjectionRelations, RemovalRelations, TargetDeviceRelationet PowerRelations.
Le membre FileObject de la structure IO_STACK_LOCATION actuelle pointe vers un objet de fichier valide uniquement si Parameters.QueryDeviceRelations.Type est TargetDeviceRelation.
Paramètres de sortie
Retourné dans le bloc d’état d’E/S.
Bloc d’état d’E/S
Un pilote définit Irp->IoStatus.Status sur STATUS_SUCCESS ou sur un état d’échec tel que STATUS_INSUFFICIENT_RESOURCES.
En cas de réussite, un pilote définit Irp->IoStatus.Information à un pointeur PDEVICE_RELATIONS qui pointe vers les informations de relations demandées. La structure DEVICE_RELATIONS est définie comme suit :
typedef struct _DEVICE_RELATIONS {
ULONG Count;
PDEVICE_OBJECT Objects[1]; // variable length
} DEVICE_RELATIONS, *PDEVICE_RELATIONS;
Opération
Si un pilote retourne des relations en réponse à cette IRP_MN_QUERY_DEVICE_RELATIONS, le pilote alloue une structure DEVICE_RELATIONS à partir de la mémoire paginée qui contient un nombre et le nombre approprié de pointeurs d’objet de périphérique. Le gestionnaire PnP libère la structure lorsqu’il n’est plus nécessaire. Si un pilote remplace une structure DEVICE_RELATIONS allouée par un autre pilote, le pilote doit libérer la structure précédente.
Un pilote doit référencer la PDO d’un appareil qu’il signale dans cet IRP (ObReferenceObject). Le gestionnaire PnP supprime la référence le cas échéant.
Un pilote de fonction ou de filtre doit être prêt à gérer cet IRP pour un appareil à tout moment après son AddDevice routine s’est terminée pour l’appareil. Les pilotes de bus doivent être prêts à gérer une requête pour BusRelations immédiatement après l’énumération d’un appareil.
Pour connaître les règles générales relatives à la gestion des irps mineures Plug-and-Play voir Plug-and-Play.
Les sous-sections suivantes décrivent les actions spécifiques pour la gestion des différentes requêtes.
Demande BusRelations
Lorsque le gestionnaire PnP interroge les relations de bus (périphériques enfants) d’une carte ou d’un contrôleur, le pilote de bus doit retourner une liste de pointeurs vers les PPO de tous les appareils physiquement présents sur le bus. Le pilote de bus signale tous les appareils, qu’ils aient été démarrés ou non. Le pilote de bus peut avoir besoin d’alimenter son appareil bus pour déterminer quels enfants sont présents.
Avertissement Un objet d’appareil ne peut pas être passé à une routine qui prend un PDO comme argument jusqu’à ce que le gestionnaire PnP crée un nœud d’appareil (devnode) pour cet objet. (Si le pilote transmet un objet d’appareil, le système vérifie les bogues avec 0xCA : PNP_DETECTED_FATAL_ERROR.) Le gestionnaire PnP crée le devnode en réponse à la requête IRP_MN_QUERY_DEVICE_RELATIONS. Le pilote peut supposer en toute sécurité que le devnode du PDO a été créé lorsqu’il reçoit une demande de IRP_MN_QUERY_RESOURCE_REQUIREMENTS.
Le pilote de bus qui répond à cet IRP est le pilote de fonction pour l’adaptateur ou le contrôleur de bus, et non le pilote de bus parent pour le bus auquel l’adaptateur ou le contrôleur est connecté. Les pilotes de fonction pour les appareils non bus ne gèrent pas cette requête. Ces pilotes passent simplement l’IRP au pilote inférieur suivant. (Voir la figure suivante.) Les pilotes de filtre ne gèrent généralement pas cette requête.
Sur les systèmes d’exploitation Windows Vista et ultérieurs, nous vous recommandons de toujours pender le IRP_MN_QUERY_DEVICE_RELATIONS IRP et de terminer son traitement ultérieurement. Cet ordre permet au système de traiter les requêtes de relation bus de manière asynchrone. (Sur les systèmes d’exploitation avant Windows Vista, les pilotes peuvent retourner en toute sécurité STATUS_PENDING à partir de leurs routines de répartition, mais le gestionnaire PnP ne chevauche pas la requête de relation de bus avec toute autre opération.)
Le diagramme suivant montre comment les pilotes gèrent une requête pour les relations de bus.
Dans l’exemple illustré dans la figure, le gestionnaire PnP envoie un IRP_MN_QUERY_DEVICE_RELATIONS pour BusRelations aux pilotes du périphérique du hub USB. Le gestionnaire PnP demande une liste des enfants de l’appareil hub.
Comme avec tous les irps PnP, le gestionnaire PnP envoie l’IRP au pilote supérieur dans la pile des appareils pour l’appareil.
Un pilote de filtre facultatif peut être le pilote supérieur de la pile. Un pilote de filtre ne gère généralement pas cette IRP ; il transmet l’IRP vers le bas de la pile. Un pilote de filtre peut gérer cet IRP, par exemple si le pilote expose un périphérique non énumérable sur le bus.
Le pilote de bus du hub USB gère l’IRP.
Pilote de bus du hub USB :
Crée une PDO pour tout appareil enfant qui n’en a pas déjà un.
Marque l’inactif PDO pour tout appareil qui n’est plus présent sur le bus. Le pilote de bus ne supprime pas ces PPO.Pour plus d’informations sur la suppression des PPO, consultez Suppression d’un appareil.
Signale tous les appareils enfants présents sur le bus.
Pour chaque périphérique enfant, le pilote de bus fait référence à l’application PDO et place un pointeur vers l’objet PDO dans la structure DEVICE_RELATIONS.
Il existe deux PDO dans cet exemple : un pour l’appareil joystick et un pour l’appareil clavier.
Le pilote de bus doit vérifier si un autre pilote a déjà créé une structure de DEVICE_RELATIONS pour cet IRP. Si c’est le cas, le pilote de bus doit ajouter aux informations existantes.
S’il n’existe aucun appareil enfant présent sur le bus, le pilote définit le nombre sur zéro dans la structure DEVICE_RELATIONS et retourne la réussite.
Définit les valeurs appropriées dans le bloc d’état d’E/S et passe l’IRP au pilote inférieur suivant. Le pilote de bus pour l’adaptateur ou le contrôleur ne termine pas l’IRP.
Un filtre inférieur facultatif, s’il est présent, ne gère généralement pas cet IRP. Un tel pilote de filtre transmet l’IRP vers le bas de la pile. Si un pilote de filtre inférieur gère cet IRP, il peut ajouter des PDO à la liste des appareils enfants, mais il ne doit pas supprimer les PDO créés par d’autres pilotes.
Le pilote de bus parent ne gère pas cet IRP, sauf s’il s’agit du seul pilote dans la pile d’appareils (l’appareil est en mode brut). Comme avec tous les irps PnP, le pilote de bus parent termine l’IRP avec IoCompleteRequest.
S’il existe un ou plusieurs pilotes de filtre de bus dans la pile d’appareils, ces pilotes peuvent gérer l’IRP sur son chemin jusqu’au pilote de bus et/ou sur le chemin de l’IRP de sauvegarder la pile d’appareils (s’il existe IoCompletion routines). Selon les règles pnP IRP, un tel pilote peut ajouter des PDP à l’IRP sur sa route vers le bas de la pile et/ou modifier la liste des relations sur la façon de sauvegarder la pile (dans IoCompletion routines).
demande ejectionRelations
Un pilote retourne des pointeurs vers des PDA de tous les appareils qui peuvent être physiquement supprimés du système lorsque l’appareil spécifié est éjecté. Ne signalez pas les PPO des enfants de l’appareil ; le gestionnaire PnP demande toujours que les appareils enfants soient supprimés avant leur appareil parent.
Le gestionnaire PnP envoie un IRP IRP_MN_EJECT à un appareil éjecté. Le pilote d’un tel appareil reçoit également un IRP de suppression. Les relations d’éjection de l’appareil reçoivent un IRP IRP_MN_REMOVE_DEVICE (pas un IRP IRP_MN_EJECT).
Seul un pilote de bus parent peut répondre à un EjectionRelations requête pour l’un de ses appareils enfants. Les pilotes de fonction et de filtre doivent le passer au pilote inférieur suivant dans la pile d’appareils. Si un pilote de bus reçoit cet IRP comme pilote de fonction pour son adaptateur ou contrôleur, le pilote de bus effectue les tâches d’un pilote de fonction et doit passer l’IRP au pilote inférieur suivant.
demande PowerRelations
À compter de Windows 7, la requête PowerRelations permet à un pilote de spécifier une relation de gestion de l’alimentation en dehors de la relation conventionnelle entre un bus parent qui prend en charge l’énumération PnP et un appareil enfant énuméré sur le bus. Par exemple, si un pilote de bus ne peut pas énumérer un appareil enfant sur le bus ou si un appareil est un enfant de plusieurs bus, la requête PowerRelations peut décrire les relations d’alimentation de l’appareil enfant avec le bus ou les bus.
Le gestionnaire PnP émet une requête PowerRelations pour un appareil lorsque le pilote de l’appareil appelle la routine IoInvalidateDeviceRelations et spécifie une valeur de paramètre Type de PowerRelations.
En réponse à cette requête, le pilote de l’appareil cible (c’est-à-dire l’appareil qui est la cible de la requête) fournit une structure DEVICE_RELATIONS qui contient des pointeurs vers les PDO de tous les autres appareils qui doivent être activés par le gestionnaire d’alimentation avant que l’appareil cible soit activé. À l’inverse, ces autres appareils doivent être désactivés uniquement une fois l’appareil cible désactivé. Le gestionnaire d’alimentation utilise les informations de la requête pour garantir que ces appareils sont activés et désactivés dans l’ordre correct.
Cette garantie de classement s’applique uniquement aux transitions d’état de veille du système global, qui incluent les transitions vers et à partir des états d’alimentation système S1, S2, S3 (veille), S4 (veille prolongée) et S5 (arrêter). La garantie de classement PowerRelations ne s’applique pas aux transitions d’état de l’alimentation de l’appareil Dx pendant que le système reste dans l’état du système S0 (en cours d’exécution), sauf dans le cas de direct runtime Power Management (DFx) transitions.
Si l’appareil cible se trouve sur le chemin d’accès d’un fichier spécial (tel que le fichier de pagination, le fichier en veille prolongée ou le fichier de vidage sur incident), le pilote de l’appareil cible doit effectuer une étape supplémentaire lorsqu’il gère un IRP IRP_MN_DEVICE_USAGE_NOTIFICATION dans lequel InPath est TRUE. Ce pilote doit s’assurer que les appareils dont les PPO sont fournis pour la requête PowerRelations peuvent également prendre en charge le chemin d’accès de l’appareil pour le fichier spécial. Pour confirmer cette prise en charge, le pilote de l’appareil cible doit d’abord envoyer le IRP_MN_DEVICE_USAGE_NOTIFICATION IRP à chacun de ces appareils, et cet IRP doit spécifier les mêmes UsageNotification.Type que l’appareil cible. Uniquement si tous les appareils qui reçoivent cet IRP terminent l’IRP avec un code d’état de réussite peut le pilote de l’appareil cible terminer son IRP_MN_DEVICE_USAGE_NOTIFICATION IRP avec succès. Dans le cas contraire, ce pilote doit terminer cet IRP avec un code d’état d’échec.
Lorsque ce même pilote gère un IRP IRP_MN_DEVICE_USAGE_NOTIFICATION pour lequel InPath est FALSE, le pilote doit envoyer le IRP_MN_DEVICE_USAGE_NOTIFICATION IRP au même ensemble d’appareils dépendants que pour le cas où InPath est TRUE. Toutefois, le pilote ne doit jamais terminer cet IRP avec un code d’état d’échec lorsque InPath est FALSE.
Le pilote qui répond à la requête PowerRelations doit s’inscrire aux notifications de modification d’appareil cible sur tous les appareils dont les PPO sont fournis pour la requête PowerRelations. Pour vous inscrire à ces notifications, le pilote peut appeler la routine IoRegisterPlugPlayNotification et spécifier une valeur de paramètre EventCategory de EventCategoryTargetDeviceChange.
request removalRelations
Un pilote retourne des pointeurs vers des PPO de tous les périphériques dont les pilotes doivent être supprimés lorsque les pilotes pour l’appareil spécifié sont supprimés. Ne signalez pas les PPO des enfants de l’appareil ; Le gestionnaire PnP demande déjà la suppression d’appareils enfants avant de supprimer un appareil.
L’ordre dans lequel les relations de suppression sont supprimées n’est pas défini.
Tout pilote de la pile d’appareils peut gérer ce type de requête de relations. Une fonction ou un pilote de filtre gère l’IRP avant de le transmettre au pilote inférieur suivant. Un pilote de bus gère l’IRP, puis le termine.
requête TargetDeviceRelation
La requête TargetDeviceRelation permet au gestionnaire PnP d’interroger une pile d’appareils non PnP pour la PDO dans la pile d’appareils PnP qui contrôle le matériel.
En règle générale, les pilotes transfèrent les IRP_MN_QUERY_DEVICE_RELATIONS IRP vers le bas de leur pile jusqu’à ce que l’IRP atteigne le bas d’une pile d’appareils particulière. Un pilote situé en bas d’une pile non PnP transfère ou transmet à nouveau l’IRP à la pile PnP appropriée. Par exemple, le gestionnaire PnP peut envoyer une requête TargetDeviceRelation à l’objet d’appareil en haut de la pile du système de fichiers, qui est une pile non PnP. Chaque objet d’appareil dans la pile du système de fichiers transmet la requête à l’objet de l’appareil sous celui-ci jusqu’à ce que la requête atteigne l’objet appareil en bas de la pile. L’objet d’appareil le plus bas dans la pile transfère ou réexécute l'TargetDeviceRelation requête vers l’objet de l’appareil en haut de la pile de volumes de stockage PnP, puis la requête est transmise à l’objet PDO en bas de la pile de volumes de stockage.
La liste suivante récapitule les situations dans lesquelles vous pouvez acquérir en toute sécurité un pointeur vers le PDO en bas d’une pile d’appareils PnP :
Objet Appareil dans un PnP
Un objet d’appareil qui se trouve dans une pile d’appareils PnP apprend à connaître l’PDO de la pile lorsque la routine AddDevice pour l’appareil est appelée. Le pilote peut mettre en cache en toute sécurité le pointeur vers l’objet PDO si l’utilisation du pointeur est correctement synchronisée avec les messages IRP_MN_REMOVE_DEVICE entrants à l’aide du supprimer les routines de verrouillage.
Objet d’appareil dans une pile non PnP, et non au bas de la pile
Pour un objet d’appareil qui n’est pas au bas d’une pile non PnP, un pilote peut envoyer une requête TargetDeviceRelation pour obtenir un pointeur vers la PDO en bas de la pile d’appareils PnP correspondante.
Objet Fichier pour l’appareil
Étant donné un objet de fichier pour l’appareil, un pilote peut appeler IoGetRelatedDeviceObject pour obtenir l’objet d’appareil, puis suivre les instructions de l’élément de liste précédent.
Gérer l’objet de l’appareil
Étant donné un handle à l’objet d’appareil, un pilote peut appeler ObReferenceObjectByHandle pour obtenir l’objet de fichier de l’appareil, puis suivre les instructions de l’élément de liste précédent.
Un pilote de bus parent doit gérer une requête de relations TargetDeviceRelation pour ses appareils enfants. Le pilote de bus fait référence à la PDO de l’appareil enfant avec ObReferenceObject et retourne un pointeur vers l’objet PDO dans la structure DEVICE_RELATIONS. Il n’existe qu’un seul pointeur PDO dans la structure pour ce type de relation. Le gestionnaire PnP supprime la référence à la PDO lorsque le pilote ou l’application annule l’inscription pour la notification sur l’appareil.
Seul un pilote de bus parent répond à une requête TargetDeviceRelation. Les pilotes de fonction et de filtre doivent le passer au pilote inférieur suivant dans la pile d’appareils. Si un pilote de bus reçoit cet IRP comme pilote de fonction pour son adaptateur ou contrôleur, le pilote de bus effectue les tâches d’un pilote de fonction et doit passer l’IRP au pilote inférieur suivant.
Si un pilote n’est pas dans une pile basée sur PDO, le pilote envoie un nouvel IRP de requête de relation de périphérique cible à l’objet d’appareil associé au handle de fichier sur lequel le pilote effectue des E/S.
l’envoi de ce IRP
Les pilotes ne doivent pas envoyer de IRP_MN_QUERY_DEVICE_RELATIONS pour demander BusRelations. Les pilotes ne sont pas limités à l’envoi de cet IRP pour RemovalRelations ou EjectionRelations, mais il n’est pas probable qu’un pilote le ferait.
Les pilotes peuvent interroger une pile d’appareils pour TargetDeviceRelation. Consultez Gestion des irps pour plus d’informations sur l’envoi d’IRPs. Les étapes suivantes s’appliquent spécifiquement à ce protocole IRP :
Définissez les valeurs dans l’emplacement de pile d’E/S suivant de l’IRP : définissez MajorFunction sur IRP_MJ_PNP, définissez MinorFunction sur IRP_MN_QUERY_DEVICE_RELATIONS, définissez Parameters.QueryDeviceRelations.Type sur TargetDeviceRelationet définissez Irp->FileObject sur un objet de fichier valide.
Initialisez IoStatus.Status à STATUS_NOT_SUPPORTED.
Si un pilote a envoyé cet IRP pour que le PDO signale en réponse à une IRP_MN_QUERY_DEVICE_RELATIONS pour TargetDeviceRelation que le pilote a reçu, le pilote signale l’opération PDO et libère la structure des relations retournées une fois l’IRP terminé. Si un pilote a lancé cet IRP pour une autre raison, le pilote libère la structure des relations lorsque l’IRP se termine et déréférence le PDO lorsqu’il n’est plus nécessaire.
Spécifications
En-tête de page |
Wdm.h (include Wdm.h, Ntddk.h ou Ntifs.h) |
Voir aussi
IoRegisterPlugPlayNotification
IRP_MN_DEVICE_USAGE_NOTIFICATION