SetupDiGetClassDevsExA, fonction (setupapi.h)
La fonction SetupDiGetClassDevsEx retourne un handle à un jeu d’informations d’appareil qui contient les éléments d’informations d’appareil demandés pour un ordinateur local ou distant.
Syntaxe
WINSETUPAPI HDEVINFO SetupDiGetClassDevsExA(
[in, optional] const GUID *ClassGuid,
[in, optional] PCSTR Enumerator,
[in, optional] HWND hwndParent,
[in] DWORD Flags,
[in, optional] HDEVINFO DeviceInfoSet,
[in, optional] PCSTR MachineName,
PVOID Reserved
);
Paramètres
[in, optional] ClassGuid
Pointeur vers le GUID d’une classe d’installation d’appareil ou d’une classe d’interface d’appareil. Ce pointeur est facultatif et peut avoir la valeur NULL. Si une valeur GUID n’est pas utilisée pour sélectionner des appareils, définissez ClassGuid surNULL. Pour plus d’informations sur l’utilisation de ClassGuid, consultez la section Remarques suivante.
[in, optional] Enumerator
Pointeur vers une chaîne terminée par NULL qui spécifie :
- Identificateur (ID) d’un énumérateur de Plug-and-Play (PnP). Cet ID peut être l’identificateur global unique (GUID) de l’énumérateur ou le nom symbolique. Par exemple, « PCI » peut être utilisé pour spécifier l’énumérateur PNP PCI. D’autres exemples de noms symboliques pour les énumérateurs PnP incluent « USB », « PCMCIA » et « SCSI ».
- Un appareil PnP instance ID. Lorsque vous spécifiez un ID de instance d’appareil PnP, DIGCF_DEVICEINTERFACE doit être défini dans le paramètre Flags.
Pour plus d’informations sur la définition de la valeur Énumérateur , consultez la section Remarques suivante.
[in, optional] hwndParent
Handle de la fenêtre de niveau supérieur à utiliser pour une interface utilisateur associée à l’installation d’un appareil instance dans l’ensemble d’informations de l’appareil. Ce handle est facultatif et peut être NULL.
[in] Flags
Variable de type DWORD qui spécifie les options de contrôle qui filtrent les éléments d’informations sur l’appareil ajoutés au jeu d’informations de l’appareil. Ce paramètre peut être un OR au niveau du bit d’un ou plusieurs des indicateurs suivants. Pour plus d’informations sur la combinaison de ces options de contrôle, consultez la section Remarques suivante.
DIGCF_ALLCLASSES
Retourne la liste des appareils installés pour les classes d’installation d’appareil ou les classes d’interface d’appareil spécifiées.
DIGCF_DEVICEINTERFACE
Retourne les appareils qui prennent en charge les interfaces d’appareil pour les classes d’interface d’appareil spécifiées. Cet indicateur doit être défini dans le paramètre Flags si le paramètre Énumérateur spécifie un ID de instance d’appareil.
DIGCF_DEFAULT
Retourne uniquement l’appareil associé à l’interface d’appareil système par défaut, le cas échéant, pour les classes d’interface d’appareil spécifiées.
DIGCF_PRESENT
Retourne uniquement les appareils actuellement présents.
DIGCF_PROFILE
Retourne uniquement les appareils qui font partie du profil matériel actuel.
[in, optional] DeviceInfoSet
Handle à un jeu d’informations d’appareil existant auquel SetupDiGetClassDevsEx ajoute les éléments d’informations d’appareil demandés. Ce paramètre est facultatif et peut être défini sur NULL. Pour plus d’informations sur l’utilisation de ce paramètre, consultez la section Remarques suivante.
[in, optional] MachineName
Pointeur vers une chaîne constante qui contient le nom d’un ordinateur distant sur lequel résident les appareils. La valeur NULL pour MachineName spécifie que l’appareil est installé sur l’ordinateur local.
Attention
L’utilisation de cette fonction pour accéder aux machines distantes n’est pas prise en charge à partir de Windows 8 et Windows Server 2012, car cette fonctionnalité a été supprimée.
Reserved
Réservé à un usage interne. Ce paramètre doit avoir la valeur NULL.
Valeur retournée
Si l’opération réussit, SetupDiGetClassDevsEx retourne un handle à un jeu d’informations sur l’appareil qui contient tous les appareils installés qui correspondent aux paramètres fournis. Si l’opération échoue, la fonction retourne INVALID_HANDLE_VALUE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Remarques
L’appelant de SetupDiGetClassDevsEx doit supprimer les informations d’appareil retournées définies quand elles ne sont plus nécessaires en appelant SetupDiDestroyDeviceInfoList.
Si DeviceInfoSet a la valeur NULL, SetupDiGetClassDevsEx crée un jeu d’informations sur l’appareil qui contient les éléments d’informations d’appareil récupérés et retourne un handle au nouvel ensemble d’informations d’appareil. Si l’appelant demande que la fonction récupère des appareils pour une classe d’installation d’appareil fournie par le paramètre ClassGuid , la fonction définit la classe d’installation de l’appareil du nouvel ensemble d’informations d’appareil sur le GUID de classe fourni.
Si DeviceInfoSet n’est pas défini sur NULL, la fonction ajoute les éléments d’informations d’appareil récupérés au jeu d’informations sur l’appareil associé au handle fourni et retourne le handle fourni. Si ClassGuid fournit une classe d’installation d’appareil, la classe d’installation de l’appareil du jeu d’informations sur l’appareil fourni doit être définie sur le GUID de classe fourni.
Options de contrôle de classe du programme d’installation de l’appareil
Utilisez les options de filtrage suivantes pour contrôler si SetupDiGetClassDevsEx retourne des appareils pour toutes les classes d’installation d’appareil ou uniquement pour une classe d’installation d’appareil spécifiée :- Pour retourner des appareils pour toutes les classes d’installation d’appareil, définissez l’indicateur DIGCF_ALLCLASSES et définissez le paramètre ClassGuid sur NULL.
- Pour renvoyer des appareils uniquement pour une classe d’installation d’appareil spécifique, ne définissez pas DIGCF_ALLCLASSES et utilisez ClassGuid pour fournir le GUID de la classe d’installation de l’appareil.
- Pour renvoyer uniquement les appareils présents dans le système, définissez l’indicateur DIGCF_PRESENT.
- Pour renvoyer uniquement les appareils qui font partie du profil matériel actuel, définissez l’indicateur DIGCF_PROFILE.
- Pour retourner des appareils pour un énumérateur PnP spécifique uniquement, utilisez le paramètre Énumérateur pour fournir le GUID ou le nom symbolique de l’énumérateur. Si Enumerator a la valeur NULL, SetupDiGetClassDevsEx retourne des appareils pour tous les énumérateurs PnP.
Options de contrôle de classe d’interface d’appareil
Utilisez les options de filtrage suivantes pour contrôler si SetupDiGetClassDevsEx retourne les appareils qui prennent en charge n’importe quelle classe d’interface d’appareil ou uniquement les appareils qui prennent en charge une classe d’interface d’appareil spécifiée :- Pour retourner des appareils qui prennent en charge une interface d’appareil de n’importe quelle classe, définissez l’indicateur DIGCF_DEVICEINTERFACE, définissez l’indicateur DIGCF_ALLCLASSES et définissez ClassGuid sur NULL. La fonction ajoute au jeu d’informations sur l’appareil un élément d’informations sur l’appareil qui représente un tel appareil, puis ajoute à l’élément d’informations sur l’appareil une liste d’interface d’appareil qui contient toutes les interfaces d’appareil prises en charge par l’appareil.
- Pour renvoyer uniquement les appareils qui prennent en charge une interface d’appareil d’une classe spécifiée, définissez l’indicateur DIGCF_DEVICEINTERFACE et utilisez le paramètre ClassGuid pour fournir le GUID de classe de la classe d’interface d’appareil. La fonction ajoute au jeu d’informations sur l’appareil un élément d’informations sur l’appareil qui représente un tel appareil, puis ajoute une interface d’appareil de la classe spécifiée à la liste d’interface de l’appareil pour cet élément d’informations sur l’appareil.
- Pour renvoyer uniquement l’appareil qui prend en charge l’interface système par défaut, le cas échéant, pour une classe d’interface d’appareil spécifiée, définissez l’indicateur DIGCF_DEVICEINTERFACE, définissez l’indicateur DIGCF_DEFAULT et utilisez ClassGuid pour fournir le GUID de classe de la classe d’interface d’appareil. La fonction ajoute au jeu d’informations sur l’appareil un élément d’informations sur l’appareil qui représente un tel appareil, puis ajoute l’interface système par défaut à la liste d’interface d’appareil pour cet élément d’informations sur l’appareil.
- Pour renvoyer un appareil qui prend en charge une interface système par défaut pour une classe d’interface d’appareil non spécifiée, définissez l’indicateur DIGCF_DEVICEINTERFACE, définissez l’indicateur DIGCF_ALLCLASSES, définissez l’indicateur DIGCF_DEFAULT et définissez ClassGuid sur NULL. La fonction ajoute au jeu d’informations sur l’appareil un élément d’informations sur l’appareil qui représente un tel appareil, puis ajoute l’interface système par défaut à la liste d’interface d’appareil pour cet élément d’informations sur l’appareil.
- Pour renvoyer uniquement les appareils présents dans le système, définissez l’indicateur DIGCF_PRESENT.
- Pour renvoyer uniquement les appareils qui font partie du profil matériel actuel, définissez l’indicateur DIGCF_PROFILE.
- Pour renvoyer uniquement un appareil spécifique, définissez l’indicateur DIGCF_DEVICEINTERFACE et utilisez le paramètre Énumérateur pour fournir l’ID de instance de l’appareil. Pour inclure tous les appareils possibles, définissez Énumérateur sur NULL.
Récupération d’appareils dans une classe device Setup qui prend en charge une classe d’interface d’appareil
Un programme d’installation peut utiliser SetupDiGetClassDevsEx pour récupérer une liste d’appareils d’une classe d’installation d’appareil particulière qui prend en charge une interface d’appareil d’une classe d’interface d’appareil spécifiée. Par exemple, pour récupérer la liste de tous les appareils sur un ordinateur local qui prennent en charge une interface d’appareil dans la classe d’interface « appareil monté » et qui sont membres de la classe d’installation d’appareil « Volume », un programme d’installation doit effectuer les opérations suivantes :- Appelez SetupDiCreateDeviceInfoList pour créer un jeu d’informations d’appareil vide pour la classe d’installation de l’appareil « Volume ». Définissez ClassGuid sur un pointeur vers le GUID de classe pour la classe d’installation de l’appareil « Volume » et définissez hwndParent comme il convient. En réponse à un tel appel, la fonction retourne un handle de type HDEVINFO au jeu d’informations de l’appareil.
- Appelez SetupDiGetClassDevsEx avec les paramètres suivants :
- Définissez ClassGuid sur un pointeur vers le GUID de classe de la classe d’interface d’appareil « appareil monté ».
- Définissez Indicateurs sur DIGCF_DEVICEINTERFACE.
- Définissez DeviceInfoSet sur le handle HDEVINFO obtenu à l’étape (1).
- Définissez hwndParent comme approprié et les paramètres restants sur NULL.
Notes
L’en-tête setupapi.h définit SetupDiGetClassDevsEx comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Configuration requise
Condition requise | Valeur |
---|---|
Client minimal pris en charge | Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows. |
Plateforme cible | Desktop (Expérience utilisateur) |
En-tête | setupapi.h (inclure Setupapi.h) |
Bibliothèque | Setupapi.lib |