Fonction IoSetDeviceInterfaceState (wdm.h)

Article
02/29/2024

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
STATUS_OBJECT_NAME_NOT_FOUND	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)