Fonction IoSetDeviceInterfaceState (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’interface de l’appareil instance en cours d’activation ou de désactivation. 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 retournée
IoSetDeviceInterfaceState retourne STATUS_SUCCESS si l’appel a réussi. Cette routine retourne une status d’information de STATUS_OBJECT_NAME_EXISTS si l’appelant a demandé à activer une interface d’appareil qui était déjà activée. Les valeurs de retour d’erreur possibles sont décrites ci-dessous.
| Code de retour | Description |
|---|---|
|
L’appelant a essayé de désactiver une interface d’appareil qui n’était pas activée. |
Remarques
IoSetDeviceInterfaceState active une instance d’une interface d’appareil inscrite pour une utilisation par les applications et d’autres composants système. La classe d’interface doit avoir été précédemment inscrite auprès de IoRegisterDeviceInterface ou à partir du mode utilisateur.
Les applications et 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 Enable défini sur TRUE après qu’il a correctement démarré un appareil en réponse à une IRP IRP_MN_START_DEVICE . Un tel pilote doit désactiver l’interface de l’appareil instance (c’est-à-dire appeler IoSetDeviceInterfaceState et définir Activer sur FALSE) 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 IRP de suppression, le pilote ne doit pas tenter de le faire par la suite, 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 interface d’appareil valide instance, 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 interface d’appareil instance, qui existera au même chemin d’accès de Registre que l’interface d’appareil existante instance.
Notez que si le pilote appelle IoSetDeviceInterfaceState pour désactiver une interface de périphérique instance en réponse à une IRP IRP_MN_SURPRISE_REMOVAL, le pilote ne doit pas tenter de désactiver la même interface de périphérique instance en réponse à une IRP IRP_MN_REMOVE_DEVICE.
Si un appel à IoSetDeviceInterfaceState expose correctement une interface d’appareil instance, le système avertit tous les composants inscrits pour la notification PnP d’un changement de classe d’appareil. De même, si un appel à cette routine désactive une interface d’appareil existante instance, le système envoie les notifications appropriées.
Le gestionnaire PnP n’envoie pas de notification de l’interface instance arrivées tant que la IRP_MN_START_DEVICE IRP n’est pas terminée, indiquant que tous les pilotes de l’appareil ont terminé leurs opérations de démarrage. En outre, le gestionnaire PnP ne parvient pas à créer des demandes pour l’appareil jusqu’à ce que la IRP_MN_START_DEVICE IRP se termine.
Les appelants d’IoSetDeviceInterfaceState doivent s’exécuter sur IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible à partir de Windows 2000. |
| Plateforme cible | Universal |
| 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) |