Fonction IoReportDetectedDevice (ntddk.h)

La routine IoReportDetectedDevice signale un appareil non PnP au gestionnaire PnP.

Syntaxe

NTSTATUS IoReportDetectedDevice(
  [in]           PDRIVER_OBJECT                 DriverObject,
  [in]           INTERFACE_TYPE                 LegacyBusType,
  [in]           ULONG                          BusNumber,
  [in]           ULONG                          SlotNumber,
  [in, optional] PCM_RESOURCE_LIST              ResourceList,
  [in, optional] PIO_RESOURCE_REQUIREMENTS_LIST ResourceRequirements,
  [in]           BOOLEAN                        ResourceAssigned,
  [in, out]      PDEVICE_OBJECT                 *DeviceObject
);

Paramètres

[in] DriverObject

Pointeur vers l’objet pilote du pilote qui a détecté l’appareil.

[in] LegacyBusType

Spécifie le type de bus sur lequel réside l’appareil. Le gestionnaire PnP utilise ces informations pour faire correspondre l’appareil signalé à son instance pnP, le cas échéant.

Les types d’interface, tels que PCIBus, sont définis dans Wdm.h. Si un pilote ne connaît pas le LegacyBusType pour l’appareil, le pilote fournit la valeur InterfaceTypeUndefined pour ce paramètre.

[in] BusNumber

Spécifie le numéro de bus de l’appareil. Le gestionnaire PnP utilise ces informations pour faire correspondre l’appareil signalé à son instance pnP, le cas échéant.

Le numéro de bus distingue le bus sur lequel réside l’appareil des autres bus du même type sur l’ordinateur. Le schéma de numérotation des bus est spécifique au bus. Si un pilote ne connaît pas le Numéro de bus pour l’appareil, il fournit la valeur -1 pour ce paramètre.

[in] SlotNumber

Spécifie le numéro d’emplacement logique de l’appareil. Le gestionnaire PnP utilise ces informations pour faire correspondre l’appareil signalé à son instance pnP, le cas échéant.

Si un pilote ne connaît pas le SlotNumber pour l’appareil, le pilote fournit la valeur -1 pour ce paramètre.

[in, optional] ResourceList

Pointeur vers la liste de ressources que le pilote a utilisé pour détecter l’appareil. Les ressources de cette liste sont sous forme brute et non traduite.

[in, optional] ResourceRequirements

Pointe éventuellement vers une liste des besoins en ressources pour l’appareil détecté. NULL si l’appelant ne dispose pas de ces informations pour l’appareil.

[in] ResourceAssigned

Spécifie si les ressources de l’appareil ont déjà été signalées au gestionnaire PnP. Si ResourceAssigned a la valeur TRUE, les ressources ont déjà été signalées, éventuellement avec IoReportResourceForDetection, et le gestionnaire PnP ne tentera pas de les réclamer au nom de l’appareil. Si la valeur est TRUE, le gestionnaire PnP ne réclame pas non plus de ressources lorsque l’appareil est énuméré à la racine lors des démarrages suivants.

[in, out] DeviceObject

Pointe éventuellement vers un AOP pour l’appareil détecté.

NULL si l’appelant n’a pas d’AOP pour l’appareil, ce qui est généralement le cas. Si DeviceObject a la valeur NULL, le gestionnaire PnP crée un PDO pour l’appareil et retourne un pointeur vers l’appelant.

Si l’appelant fournit un PDO, le gestionnaire PnP ne crée pas d’AOP. Lors d’un appel donné à cette routine, le paramètre DeviceObject est un paramètre IN ou OUT, mais pas les deux.

Valeur retournée

IoReportDetectedDevice retourne STATUS_SUCCESS en cas de réussite ou le code d’erreur approprié en cas d’échec.

Remarques

Les pilotes des appareils hérités utilisent IoReportDetectedDevice pour signaler leurs appareils au système. Un pilote doit uniquement appeler IoReportDetectedDevice pour signaler un appareil non PnP hérité. Les appareils PnP doivent être signalés en réponse à une demande de IRP_MN_QUERY_DEVICE_RELATIONS .

Les pilotes doivent uniquement appeler IoReportDetectedDevice la première fois qu’ils sont chargés, car le gestionnaire PnP met en cache les informations signalées. Les pilotes qui utilisent cette routine doivent stocker un indicateur dans le Registre pour indiquer s’ils ont déjà effectué la détection des appareils.

Un pilote appelle généralement cette routine à partir de sa routine DriverEntry . Certains pilotes, comme certains pilotes NDIS ou EISA, peuvent appeler cette routine à partir d’une routine AddDevice .

Une fois IoReportDetectedDevice terminé, l’appelant doit attacher un FDO au PDO retourné dans DeviceObject. Une fois que l’appelant attache son FDO, l’appelant est le pilote de fonction de l’appareil, au moins temporairement. Il n’existe aucun pilote de filtre. Le gestionnaire PnP est propriétaire de l’AOP.

Le gestionnaire PnP considère que l’appareil est démarré et n’appelle donc pas la routine AddDevice du pilote et n’envoie pas de requête IRP_MN_START_DEVICE . Toutefois, le pilote doit être prêt à gérer tous les autres IIP PnP.

IoReportDetectedDevice marque l’appareil comme un appareil racine et cette identification est persistante entre les démarrages système. Lors du démarrage du système suivant, le gestionnaire PnP « détecte » l’appareil figurant dans la liste racine et le configure comme un appareil PnP : le gestionnaire PnP interroge les informations sur l’appareil, identifie les pilotes appropriés et appelle leurs routines AddDevice et envoie tous les adresses IP PnP appropriées.

Le système génère deux chaînes d’ID compatibles pour l’appareil, sous la forme DETECTEDInterface\Driver et DETECTED\Driver. Interface est le nom de chaîne du INTERFACE_TYPE du premier bus spécifié dans le paramètre ResourceList . L’interface est définie sur « Interne » si aucun bus n’est spécifié. Le pilote est le nom du service du pilote. Un pilote peut fournir des ID matériels supplémentaires ou des ID compatibles en gérant la demande IRP_MN_QUERY_ID .

Un enregistreur de pilotes doit fournir un fichier INF qui correspond à l’un des ID matériels spécifiés ou aux ID compatibles. Le fichier INF doit spécifier le pilote d’origine qui a appelé IoReportDetectedDevice comme pilote à charger pour ces ID. Le système utilise ces informations pour reconstruire la pile de pilotes de l’appareil, par exemple au redémarrage. Les appelants d’IoReportDetectedDevice doivent s’exécuter à IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.

Configuration requise

Voir aussi

IRP_MN_QUERY_DEVICE_RELATIONS

IoReportResourceForDetection