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 énumérée 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 énumérée PnP, le cas échéant.
Le numéro de bus distingue le bus sur lequel réside l’appareil à partir d’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 BusNumber pour l’appareil, le pilote 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 énumérée 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 des ressources utilisée pour détecter l’appareil. Les ressources de cette liste sont sous forme brute et non convertie.
[in, optional] ResourceRequirements
Pointe éventuellement vers une liste des exigences de ressources pour l’appareil détecté. NULL si l’appelant n’a pas 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 est TRUE, les ressources ont déjà été signalées, éventuellement avec IoReportResourceForDetection, et le gestionnaire PnP ne tentera pas de les revendiquer pour le compte de l’appareil. Si TRUE, le gestionnaire PnP ne réclame pas non plus les ressources lorsque l’appareil est énuméré à la racine lors des démarrages suivants.
[in, out] DeviceObject
Si vous le souhaitez, pointez vers une PDO pour l’appareil détecté.
NULL si l’appelant n’a pas de PDO pour l’appareil, ce qui est généralement le cas. Si DeviceObject est NULL, le gestionnaire PnP crée un PDO pour l’appareil et retourne un pointeur vers l’appelant.
Si l’appelant fournit une PDO, le gestionnaire PnP ne crée pas de PDO. Lors d’un appel donné à cette routine, le paramètre DeviceObject est un paramètre IN ou OUT, mais pas les deux.
Valeur de retour
IoReportDetectedDevice retourne STATUS_SUCCESS en cas de réussite ou le code d’erreur approprié en cas d’échec.
Remarques
Les pilotes pour les appareils hérités utilisent IoReportDetectedDevice pour signaler leurs appareils au système. Un pilote doit uniquement appeler IoReportDetectedDevice pour signaler un appareil hérité, non PnP. 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. Quelques pilotes, comme certains pilotes NDIS ou EISA, peuvent appeler cette routine à partir d’un AddDevice routine.
Une fois l’exécution réussie de IoReportDetectedDevice, l’appelant doit attacher une FDO à l’objet PDO retourné à 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 possède l’objet PDO.
Le gestionnaire PnP considère que l’appareil est démarré et n’appelle donc pas la routine d'AddDevice du pilote et n’envoie pas de demande de IRP_MN_START_DEVICE. Toutefois, le pilote doit être prêt à gérer tous les autres fournisseurs d’intégration PnP.
IoReportDetectedDevice marque l’appareil en tant qu’appareil énuméré à la racine et cette identification est persistante entre les démarrages système. Pendant le démarrage du système suivant, le gestionnaire PnP « détecte » l’appareil dans la liste énumérée par la 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 AddDevice routines et envoie toutes 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. 'interface est définie sur « Interne » si aucun bus n’est spécifié. driver 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 de 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 en tant que pilote à charger pour ces ID. Le système utilise ces informations pour reconstruire la pile des pilotes pour l’appareil, par exemple lors du redémarrage. Les appelants de IoReportDetectedDevice doivent s’exécuter à IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 2000. |
| plateforme cible | Universel |
| d’en-tête | ntddk.h (include Ntddk.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (voir la section Remarques) |
| règles de conformité DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |