Fonction IoGetDeviceInterfaces (wdm.h)

Article
02/29/2024

La routine IoGetDeviceInterfaces retourne une liste d’instances d’interface d’appareil d’une classe d’interface d’appareil particulière (par exemple, tous les appareils du système qui prennent en charge une interface HID).

Syntaxe

NTSTATUS IoGetDeviceInterfaces(
  [in]           const GUID     *InterfaceClassGuid,
  [in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
  [in]           ULONG          Flags,
  [out]          PZZWSTR        *SymbolicLinkList
);

Paramètres

[in] InterfaceClassGuid

Pointeur vers un GUID de classe spécifiant la classe d’interface de périphérique. Les GUID d’une classe doivent se trouver dans un fichier d’en-tête spécifique à l’appareil.

[in, optional] PhysicalDeviceObject

Pointeur vers un PDO facultatif qui limite la recherche aux seules instances d’interface d’appareil de l’appareil représenté par l’AOP.

[in] Flags

Spécifie les indicateurs qui modifient la recherche d’interfaces d’appareil. Un seul indicateur est actuellement défini et est décrit dans le tableau suivant.

Indicateur	Signification
DEVICE_INTERFACE_INCLUDE_NONACTIVE	Retourne des instances d’interface d’appareil désactivées en plus des instances d’interface activées.

Lors de la recherche d’un appareil qui prend en charge une classe d’interface particulière, l’appelant nécessite une instance d’interface activée et ne définit donc pas l’indicateur DEVICE_INTERFACE_INCLUDE_NONACTIVE.

Un pilote définit généralement l’indicateur DEVICE_INTERFACE_INCLUDE_NONACTIVE pour localiser les instances d’interface désactivées que le pilote doit activer. Par exemple, le programme d’installation de classe de l’appareil a peut-être été dirigé par le fichier INF pour inscrire une ou plusieurs instances d’interface pour l’appareil. Les instances d’interface sont inscrites mais ne sont pas utilisables tant qu’elles ne sont pas activées par le pilote (à l’aide de IoSetDeviceInterfaceState). Pour affiner la liste des instances d’interface retournées uniquement à celles exposées par un appareil donné, un pilote peut spécifier un PhysicalDeviceObject.

[out] SymbolicLinkList

Pointeur vers un pointeur à caractères larges dans lequel la routine, si elle réussit, écrit l’adresse de base d’une mémoire tampon qui contient une liste de chaînes Unicode. Ces chaînes sont des noms de liens symboliques qui identifient les instances d’interface d’appareil qui correspondent aux critères de recherche. Chaque chaîne Unicode de la liste est terminée par un caractère Null ; la fin de la liste entière est marquée par un caractère null supplémentaire. La routine alloue la mémoire tampon pour ces chaînes à partir de la mémoire système paginée. L’appelant est chargé de libérer la mémoire tampon (en appelant la routine ExFreePool ) quand elle n’est plus nécessaire.

Si aucune instance d’interface d’appareil ne correspond aux critères de recherche, cette routine retourne STATUS_SUCCESS et la chaîne contient un seul caractère NULL.

Valeur retournée

IoGetDeviceInterfaces retourne STATUS_SUCCESS si l’appel a réussi. Les valeurs de retour d’erreur possibles sont les suivantes.

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	Indique éventuellement que PhysicalDeviceObject n’était pas un pointeur PDO valide.

Remarques

IoGetDeviceInterfaces retourne une liste d’instances d’interface d’appareil qui correspondent aux critères de recherche. Un composant en mode noyau appelle généralement cette routine pour obtenir la liste de toutes les instances d’interface d’appareil activées d’une classe d’interface d’appareil particulière. Un tel composant peut obtenir un pointeur vers l’objet file et/ou l’objet d’appareil d’une interface en appelant la routine IoGetDeviceObjectPointer ou ZwCreateFile . Le pointeur d’objet d’appareil retourné par IoGetDeviceObjectPointer pointe vers le haut de la pile de l’appareil et peut être utilisé dans les appels à la routine IoCallDriver .

S’il existe une interface par défaut pour la classe d’interface d’appareil demandée, elle est répertoriée en premier dans SymbolicLinkList. Les interfaces par défaut peuvent être définies par mode utilisateur, mais pas par mode noyau.

Le format d’un nom de lien symbolique est opaque ; l’appelant ne doit pas essayer d’analyser un nom de lien symbolique.

Les liens symboliques pour les instances d’interface d’appareil peuvent être utilisés dans les démarrages système.

Pour être averti lorsque des instances d’interface d’appareil supplémentaires d’une classe particulière sont activées sur le système, inscrivez-vous pour recevoir la notification d’un changement de classe d’appareil en appelant la routine IoRegisterPlugPlayNotification .

Les appelants d’IoGetDeviceInterfaces 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), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)