Partager via

SetupDiGetClassDevsA, fonction (setupapi.h)

  • Article

La fonction SetupDiGetClassDevs retourne un handle à un jeu d’informations d’appareil qui contient les éléments d’informations d’appareil demandés pour un ordinateur local.

Syntaxe

WINSETUPAPI HDEVINFO SetupDiGetClassDevsA(
  const GUID *ClassGuid,
  PCSTR      Enumerator,
  HWND       hwndParent,
  DWORD      Flags
);

Paramètres

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 être NULL. Pour plus d’informations sur la définition de ClassGuid, consultez la section Remarques suivante.

Enumerator

Pointeur vers une chaîne terminée par NULL qui spécifie :

  • Identificateur (ID) d’un énumérateur Plug-and-Play (PnP). Cet ID peut être l’identificateur global unique (GUID) ou le nom symbolique de la valeur. Par exemple, « PCI » peut être utilisé pour spécifier la valeur PCI PnP. D’autres exemples de noms symboliques pour les valeurs PnP incluent « USB », « PCMCIA » et « SCSI ».
  • UN ID de instance d’appareil PnP. Lorsque vous spécifiez un ID de instance d’appareil PnP, DIGCF_DEVICEINTERFACE doit être défini dans le paramètre Flags.
Ce pointeur est facultatif et peut être NULL. Si aucune valeur d’énumération n’est utilisée pour sélectionner des appareils, définissez Énumérateur sur NULL

Pour plus d’informations sur la définition de la valeur Énumérateur , consultez la section Remarques suivante.

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.

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 sur l’appareil. Ce paramètre peut être un OR au niveau du bit de zéro ou plusieurs des indicateurs suivants. Pour plus d’informations sur la combinaison de ces indicateurs, consultez la section Remarques suivante.

DIGCF_ALLCLASSES

Retourne la liste des appareils installés pour toutes les classes d’installation d’appareil ou toutes les classes d’interface d’appareil.

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 Enumerator 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 dans un système.

DIGCF_PROFILE

Retourne uniquement les appareils qui font partie du profil matériel actuel.

Valeur retournée

Si l’opération réussit, SetupDiGetClassDevs retourne un handle à un jeu d’informations d’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 SetupDiGetClassDevs doit supprimer les informations d’appareil retournées définies quand elles ne sont plus nécessaires en appelant SetupDiDestroyDeviceInfoList.

Appelez SetupDiGetClassDevsEx pour récupérer les appareils d’une classe sur un ordinateur distant.

Options de contrôle de la classe Device Setup

Utilisez les options de filtrage suivantes pour contrôler si SetupDiGetClassDevs 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 retourner 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 d’appareil.
En outre, vous pouvez utiliser les options de filtrage suivantes en combinaison les unes avec les autres pour restreindre davantage les appareils retournés :
  • Pour retourner 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 uniquement pour un énumérateur PnP spécifique, utilisez le paramètre Enumerator pour fournir le GUID ou le nom symbolique de l’énumérateur. Si Énumérateur a la valeur NULL, SetupDiGetClassDevs retourne des appareils pour tous les énumérateurs PnP.

Options de contrôle de la classe d’interface de périphérique

Utilisez les options de filtrage suivantes pour contrôler si SetupDiGetClassDevs retourne des appareils qui prennent en charge une classe d’interface d’appareil ou uniquement des 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 d’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 d’appareil pour cet élément d’informations sur l’appareil.
En outre, vous pouvez utiliser les options de filtrage suivantes pour contrôler si SetupDiGetClassDevs retourne uniquement les appareils qui prennent en charge l’interface système par défaut pour les classes d’interface d’appareil :
  • Pour renvoyer uniquement l’appareil qui prend en charge l’interface système par défaut, s’il est défini, 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 de périphérique. 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 retourner 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.
Vous pouvez également utiliser les options suivantes en combinaison avec les autres options pour restreindre davantage les appareils retournés :
  • Pour retourner 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 Enumerator pour fournir l’ID de instance de l’appareil. Pour inclure tous les appareils possibles, définissez Énumérateur sur NULL.

Exemples

Voici quelques exemples d’utilisation de la fonction SetupDiGetClassDevs .

Exemple 1 : Créez une liste de tous les appareils du système, y compris les appareils qui ne sont pas présents actuellement.

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES);

Exemple 2 : Créez une liste de tous les appareils présents dans le système.

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES | DIGCF_PRESENT);

Exemple 3 : Créez une liste de tous les appareils présents dans le système qui proviennent de la classe de configuration de périphérique de carte réseau.

Handle = SetupDiGetClassDevs(&GUID_DEVCLASS_NET, NULL, NULL, DIGCF_PRESENT);

Exemple 4 : Créez une liste de tous les appareils présents dans le système qui ont activé une interface à partir de la classe d’interface de périphérique de volume de stockage.

Handle = SetupDiGetClassDevs(&GUID_DEVINTERFACE_VOLUME, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);

Exemple 5 : Créez une liste de tous les appareils présents dans le système, mais qui n’appartiennent à aucune classe d’installation d’appareil connue (Windows Vista et versions ultérieures de Windows).

Note Vous ne pouvez pas définir le paramètre ClassGuid sur GUID_DEVCLASS_UNKNOWN pour détecter les appareils avec une classe d’installation inconnue. Au lieu de cela, vous devez suivre cet exemple.
 
DeviceInfoSet = SetupDiGetClassDevs(
                                    NULL,
                                    NULL,
                                    NULL,
                                    DIGCF_ALLCLASSES | DIGCF_PRESENT);

ZeroMemory(&DeviceInfoData, sizeof(SP_DEVINFO_DATA));
DeviceInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
DeviceIndex = 0;
    
while (SetupDiEnumDeviceInfo(
                             DeviceInfoSet,
                             DeviceIndex,
                             &DeviceInfoData)) {
    DeviceIndex++;

    if (!SetupDiGetDeviceProperty(
                                  DeviceInfoSet,
                                  &DeviceInfoData,
                                  &DEVPKEY_Device_Class,
                                  &PropType,
                                  (PBYTE)&DevGuid,
                                  sizeof(GUID),
                                  &Size,
                                  0) || PropType != DEVPROP_TYPE_GUID) {

        Error = GetLastError();

        if (Error == ERROR_NOT_FOUND) {
            \\
            \\ This device has an unknown device setup class.
            \\
            }
        }                 
    }

if (DeviceInfoSet) {
    SetupDiDestroyDeviceInfoList(DeviceInfoSet);
    }

Notes

L’en-tête setupapi.h définit SetupDiGetClassDevs en tant qu’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. La combinaison 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 DesktopPour universel, appelez CM_Get_Device_ID_ListFor universel, appelez CM_Get_Device_Interface_List
En-tête setupapi.h (inclure SetupAPI.h)
Bibliothèque SetupAPI.lib
DLL SetupAPI.dll
Ensemble d’API ext-ms-win-setupapi-classinstallers-l1-1-2 (introduit dans Windows 10, version 10.0.14393)

Voir aussi

Jeu d’informations sur l’appareil

ID d’instance d’appareil

SetupDiCreateDeviceInfoList

SetupDiDestroyDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevsEx