Funzione SetupDiGetClassDevsW (setupapi.h)

Articolo
03/05/2024

La funzione SetupDiGetClassDevs restituisce un handle a un set di informazioni sul dispositivo contenente gli elementi di informazioni sul dispositivo richiesti per un computer locale.

Sintassi

WINSETUPAPI HDEVINFO SetupDiGetClassDevsW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCWSTR     Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags
);

Parametri

[in, optional] ClassGuid

Puntatore al GUID per una classe di configurazione del dispositivo o una classe dell'interfaccia del dispositivo. Questo puntatore è facoltativo e può essere NULL. Per altre informazioni su come impostare ClassGuid, vedere la sezione Osservazioni seguente.

[in, optional] Enumerator

Puntatore a una stringa con terminazione NULL che specifica:

Identificatore (ID) di un enumeratore Plug and Play (PnP). Questo ID può essere l'identificatore univoco globale (GUID) del valore o il nome simbolico. Ad esempio, "PCI" può essere usato per specificare il valore PCI PnP. Altri esempi di nomi simbolici per i valori PnP includono "USB", "PCMCIA" e "SCSI".
ID Istanza del dispositivo PnP. Quando si specifica un ID istanza del dispositivo PnP, DIGCF_DEVICEINTERFACE deve essere impostato nel parametro Flags.

Questo puntatore è facoltativo e può essere NULL. Se non viene usato un valore di enumerazione per selezionare i dispositivi, impostare Enumeratore su NULL

Per altre informazioni su come impostare il valore dell'enumeratore , vedere la sezione Osservazioni seguente.

[in, optional] hwndParent

Handle per la finestra di primo livello da usare per un'interfaccia utente associata all'installazione di un'istanza del dispositivo nel set di informazioni sul dispositivo. Questo handle è facoltativo e può essere NULL.

[in] Flags

Variabile di tipo DWORD che specifica le opzioni di controllo che filtrano gli elementi delle informazioni sul dispositivo aggiunti al set di informazioni sul dispositivo. Questo parametro può essere un OR bit per bit pari a zero o più dei flag seguenti. Per altre informazioni sulla combinazione di questi flag, vedere la sezione Osservazioni seguente.

DIGCF_ALLCLASSES

Restituisce un elenco di dispositivi installati per tutte le classi di configurazione del dispositivo o per tutte le classi di interfaccia del dispositivo.

DIGCF_DEVICEINTERFACE

Restituisce i dispositivi che supportano le interfacce del dispositivo per le classi di interfaccia del dispositivo specificate. Questo flag deve essere impostato nel parametro Flags se il parametro Enumerator specifica un ID istanza del dispositivo.

DIGCF_DEFAULT

Restituisce solo il dispositivo associato all'interfaccia del dispositivo predefinita del sistema, se impostata, per le classi di interfaccia dispositivo specificate.

DIGCF_PRESENT

Restituisce solo i dispositivi attualmente presenti in un sistema.

DIGCF_PROFILE

Restituisce solo i dispositivi che fanno parte del profilo hardware corrente.

Valore restituito

Se l'operazione ha esito positivo, SetupDiGetClassDevs restituisce un handle a un set di informazioni sul dispositivo che contiene tutti i dispositivi installati che corrispondono ai parametri forniti. Se l'operazione non riesce, la funzione restituisce INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Il chiamante di SetupDiGetClassDevs deve eliminare il set di informazioni sul dispositivo restituito quando non è più necessario chiamando SetupDiDestroyDeviceInfoList.

Chiamare SetupDiGetClassDevsEx per recuperare i dispositivi per una classe in un computer remoto.

Opzioni di controllo della classe Device Setup

Usare le opzioni di filtro seguenti per controllare se SetupDiGetClassDevs restituisce i dispositivi per tutte le classi di installazione del dispositivo o solo per una classe di installazione del dispositivo specificata:

Per restituire i dispositivi per tutte le classi di installazione del dispositivo, impostare il flag DIGCF_ALLCLASSES e impostare il parametro ClassGuid su NULL.
Per restituire i dispositivi solo per una classe di configurazione del dispositivo specifica, non impostare DIGCF_ALLCLASSES e usare ClassGuid per fornire il GUID della classe di installazione del dispositivo.

Inoltre, è possibile usare le opzioni di filtro seguenti in combinazione tra loro per limitare ulteriormente i dispositivi restituiti:

Per restituire solo i dispositivi presenti nel sistema, impostare il flag DIGCF_PRESENT.
Per restituire solo i dispositivi che fanno parte del profilo hardware corrente, impostare il flag di DIGCF_PROFILE.
Per restituire i dispositivi solo per un enumeratore PnP specifico, usare il parametro Enumerator per specificare il GUID o il nome simbolico dell'enumeratore. Se Enumeratore è NULL, SetupDiGetClassDevs restituisce i dispositivi per tutti gli enumeratori PnP.

Opzioni di controllo classe dell'interfaccia dispositivo

Usare le opzioni di filtro seguenti per controllare se SetupDiGetClassDevs restituisce dispositivi che supportano qualsiasi classe di interfaccia del dispositivo o solo i dispositivi che supportano una classe di interfaccia del dispositivo specificata:

Per restituire i dispositivi che supportano un'interfaccia del dispositivo di qualsiasi classe, impostare il flag di DIGCF_DEVICEINTERFACE, impostare il flag DIGCF_ALLCLASSES e impostare ClassGuid su NULL. La funzione aggiunge al set di informazioni sul dispositivo un elemento informazioni sul dispositivo che rappresenta tale dispositivo e quindi aggiunge all'elemento informazioni sul dispositivo un elenco di interfacce di dispositivo che contiene tutte le interfacce del dispositivo supportate dal dispositivo.
Per restituire solo i dispositivi che supportano un'interfaccia del dispositivo di una classe specificata, impostare il flag DIGCF_DEVICEINTERFACE e usare il parametro ClassGuid per specificare il GUID della classe dell'interfaccia del dispositivo. La funzione aggiunge al set di informazioni sul dispositivo un elemento informazioni sul dispositivo che rappresenta tale dispositivo e quindi aggiunge un'interfaccia dispositivo della classe specificata all'elenco di interfacce del dispositivo per l'elemento informazioni sul dispositivo.

Inoltre, è possibile usare le opzioni di filtro seguenti per controllare se SetupDiGetClassDevs restituisce solo i dispositivi che supportano l'interfaccia predefinita di sistema per le classi di interfaccia del dispositivo:

Per restituire solo il dispositivo che supporta l'interfaccia predefinita del sistema, se ne è impostata una, per una classe di interfaccia dispositivo specificata, impostare il flag di DIGCF_DEVICEINTERFACE, impostare il flag DIGCF_DEFAULT e usare ClassGuid per fornire il GUID della classe dell'interfaccia del dispositivo. La funzione aggiunge al set di informazioni sul dispositivo un elemento informazioni sul dispositivo che rappresenta tale dispositivo e quindi aggiunge l'interfaccia predefinita di sistema all'elenco di interfacce del dispositivo per tale elemento informazioni sul dispositivo.
Per restituire un dispositivo che supporta un'interfaccia predefinita di sistema per una classe di interfaccia del dispositivo non specificata, impostare il flag di DIGCF_DEVICEINTERFACE, impostare il flag DIGCF_ALLCLASSES, impostare il flag DIGCF_DEFAULT e impostare ClassGuid su NULL. La funzione aggiunge al set di informazioni sul dispositivo un elemento informazioni sul dispositivo che rappresenta tale dispositivo e quindi aggiunge l'interfaccia predefinita di sistema all'elenco di interfacce del dispositivo per tale elemento informazioni sul dispositivo.

È anche possibile usare le opzioni seguenti in combinazione con le altre opzioni per limitare ulteriormente i dispositivi restituiti:

Per restituire solo i dispositivi presenti nel sistema, impostare il flag DIGCF_PRESENT.
Per restituire solo i dispositivi che fanno parte del profilo hardware corrente, impostare il flag di DIGCF_PROFILE.
Per restituire solo un dispositivo specifico, impostare il flag DIGCF_DEVICEINTERFACE e usare il parametro Enumerator per specificare l'ID istanza del dispositivo. Per includere tutti i dispositivi possibili, impostare Enumeratore su NULL.

Esempio

Di seguito sono riportati alcuni esempi di come usare la funzione SetupDiGetClassDevs .

Esempio 1: Compilare un elenco di tutti i dispositivi nel sistema, inclusi i dispositivi attualmente non presenti.

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

Esempio 2: Compilare un elenco di tutti i dispositivi presenti nel sistema.

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

Esempio 3: Compilare un elenco di tutti i dispositivi presenti nel sistema che provengono dalla classe di configurazione del dispositivo della scheda di rete.

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

Esempio 4: Compilare un elenco di tutti i dispositivi presenti nel sistema che hanno abilitato un'interfaccia dalla classe dell'interfaccia del dispositivo del volume di archiviazione.

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

Esempio 5: Compilare un elenco di tutti i dispositivi presenti nel sistema, ma che non appartengono ad alcuna classe di configurazione del dispositivo nota (Windows Vista e versioni successive di Windows).

Nota Non è possibile impostare il parametro ClassGuid su GUID_DEVCLASS_UNKNOWN per rilevare i dispositivi con una classe di installazione sconosciuta. È invece necessario seguire questo esempio.

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);
    }

Nota

L'intestazione setupapi.h definisce SetupDiGetClassDevs come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Microsoft Windows 2000 e versioni successive di Windows.
Piattaforma di destinazione	DesktopFor universal, chiamare CM_Get_Device_ID_ListFor universale, chiamare CM_Get_Device_Interface_List
Intestazione	setupapi.h (include SetupAPI.h)
Libreria	SetupAPI.lib
DLL	SetupAPI.dll
Set di API	ext-ms-win-setupapi-classinstallers-l1-1-0 (introdotto in Windows 8)