IoSetDeviceInterfaceState, fonction (wdm.h)
La routine IoSetDeviceInterfaceState active ou désactive une instance d’une classe d’interface d’appareil précédemment inscrite.
Syntaxe
NTSTATUS IoSetDeviceInterfaceState(
[in] PUNICODE_STRING SymbolicLinkName,
[in] BOOLEAN Enable
);
Paramètres
[in] SymbolicLinkName
Pointeur vers une chaîne qui identifie l’instance d’interface d’appareil activée ou désactivée. Cette chaîne a été obtenue à partir d’un appel précédent à IoRegisterDeviceInterface ou IoGetDeviceInterfaces.
[in] Enable
TRUE indique que l’interface de l’appareil est activée. FALSE indique que l’interface de l’appareil est désactivée.
Valeur de retour
IoSetDeviceInterfaceState retourne STATUS_SUCCESS si l’appel a réussi. Cette routine retourne un état d’information de STATUS_OBJECT_NAME_EXISTS si l’appelant a demandé d’activer une interface d’appareil déjà activée. Les valeurs de retour d’erreur possibles sont décrites ci-dessous.
| Retourner le code | Description |
|---|---|
|
L’appelant a essayé de désactiver une interface d’appareil qui n’a pas été activée. |
Remarques
IoSetDeviceInterfaceState permet à une instance d’une interface d’appareil inscrite à utiliser par des applications et d’autres composants système. La classe d’interface doit avoir été précédemment inscrite auprès de IoRegisterDeviceInterface ou du mode utilisateur.
Les applications et d’autres composants système peuvent ouvrir uniquement les interfaces activées.
Une fonction ou un pilote de filtre appelle généralement cette routine avec Activer défini sur TRUE une fois qu’il démarre correctement un appareil en réponse à un IRP IRP_MN_START_DEVICE. Un tel pilote doit désactiver l’instance d’interface d’appareil (autrement dit, appeler IoSetDeviceInterfaceState et définir Activer sur FAUX) lorsqu’il supprime l’appareil en réponse à un IRP IRP_MN_REMOVE_DEVICE ou un IRP IRP_MN_SURPRISE_REMOVAL. Si un pilote ne désactive pas une interface de périphérique lorsqu’il traite ces irps de suppression, le pilote ne doit pas tenter par la suite de le faire, car le gestionnaire PnP désactive l’interface lorsque le gestionnaire PnP supprime l’appareil.
Si un appareil est supprimé soudainement (par exemple, par une suppression surprise) mais qu’il a toujours une instance d’interface d’appareil valide, un problème se produit si l’appareil est attaché. Ce problème se produit lorsque le gestionnaire PnP énumère l’appareil nouvellement attaché et active une instance d’interface d’appareil, qui existera au même chemin de Registre que l’instance d’interface d’appareil existante.
Notez que si le pilote appelle IoSetDeviceInterfaceState pour désactiver une instance d’interface d’appareil en réponse à un IRP IRP_MN_SURPRISE_REMOVAL, le pilote ne doit pas tenter de désactiver la même instance d’interface d’appareil en réponse à un IRP IRP_MN_REMOVE_DEVICE.
Si un appel à IoSetDeviceInterfaceState expose correctement une instance d’interface d’appareil, le système avertit tous les composants inscrits pour la notification PnP d’une modification de classe d’appareil. De même, si un appel à cette routine désactive une instance d’interface d’appareil existante, le système envoie des notifications appropriées.
Le gestionnaire PnP n’envoie pas de notification d’arrivées d’instance d’interface tant que le IRP_MN_START_DEVICE IRP n’est pas terminé, indiquant que tous les pilotes de l’appareil ont terminé leurs opérations de démarrage. En outre, le gestionnaire PnP échoue à créer des demandes pour l’appareil jusqu’à ce que le IRP_MN_START_DEVICE IRP se termine.
Les appelants de IoSetDeviceInterfaceState 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 | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (voir la section Remarques) |
| règles de conformité DDI | HwStorPortProhibitedDDIs(storport), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm) |