Funzione SetupDiGetClassDevsExA (setupapi.h)

  • Articolo

La funzione SetupDiGetClassDevsEx restituisce un handle a un set di informazioni sul dispositivo che contiene elementi di informazioni sul dispositivo richiesti per un computer locale o remoto.

Sintassi

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

Parametri

[in, optional] ClassGuid

Puntatore al GUID per una classe di configurazione del dispositivo o a una classe di interfaccia del dispositivo. Questo puntatore è facoltativo e può essere NULL. Se un valore GUID non viene usato per selezionare i dispositivi, impostare ClassGuid su NULL. Per altre informazioni sull'uso di ClassGuid, vedere la sezione Osservazioni seguenti.

[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) dell'enumeratore o il nome simbolico. Ad esempio, è possibile usare "PCI" per specificare l'enumeratore PCI PnP. Altri esempi di nomi simbolici per gli enumeratori 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 enumeratore per selezionare i dispositivi, impostare Enumerator su NULL

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

[in, optional] hwndParent

Handle alla 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 del dispositivo aggiunti al set di informazioni del dispositivo. Questo parametro può essere un OR bit per bit di uno o più dei flag seguenti. Per altre informazioni sulla combinazione di queste opzioni di controllo, vedere la sezione Osservazioni seguenti.

DIGCF_ALLCLASSES

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

DIGCF_DEVICEINTERFACE

Restituisce i dispositivi che supportano le interfacce dispositivo per le classi di interfaccia del dispositivo specificate. Questo flag deve essere impostato nel parametro Flags se il parametro Enumeratore 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.

DIGCF_PROFILE

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

[in, optional] DeviceInfoSet

L'handle a un set di informazioni sul dispositivo esistente su cui SetupDiGetClassDevsEx aggiunge gli elementi di informazioni sul dispositivo richiesti. Questo parametro è facoltativo e può essere impostato su NULL. Per altre informazioni sull'uso di questo parametro, vedere la sezione Osservazioni seguenti.

[in, optional] MachineName

Puntatore a una stringa costante contenente il nome di un computer remoto in cui risiedono i dispositivi. Un valore null per MachineName specifica che il dispositivo è installato nel computer locale.

Attenzione

L'uso di questa funzione per accedere ai computer remoti non è supportato a partire da Windows 8 e Windows Server 2012, perché questa funzionalità è stata rimossa.

Reserved

Riservato per utilizzo interno. Questo parametro deve essere impostato su NULL.

Valore restituito

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

Commenti

Il chiamante di SetupDiGetClassDevsEx deve eliminare le informazioni del dispositivo restituite quando non è più necessario chiamando SetupDiDestroyDeviceInfoList.

Se DeviceInfoSet è NULL, SetupDiGetClassDevsEx crea un nuovo set di informazioni sul dispositivo contenente gli elementi delle informazioni del dispositivo recuperati e restituisce un handle al nuovo set di informazioni sul dispositivo. Se il chiamante richiede che la funzione recupera i dispositivi per una classe di installazione del dispositivo fornita dal parametro ClassGuid , la funzione imposta la classe di installazione del dispositivo del nuovo set di informazioni sul dispositivo impostata sul GUID della classe specificata.

Se DeviceInfoSet non è impostato su NULL, la funzione aggiunge gli elementi delle informazioni sul dispositivo recuperati al set di informazioni sul dispositivo associato all'handle fornito e restituisce l'handle fornito. Se ClassGuid fornisce una classe di configurazione del dispositivo, la classe di configurazione del dispositivo del set di informazioni del dispositivo fornito deve essere impostata sul GUID della classe specificata.

Opzioni di controllo della classe di installazione del dispositivo

Usare le opzioni di filtro seguenti per controllare se SetupDiGetClassDevsEx restituisce i dispositivi per tutte le classi di installazione del dispositivo o solo per una classe di configurazione 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 specificare il GUID della classe di installazione del dispositivo.
È inoltre possibile usare le opzioni di filtro seguenti per limitare ulteriormente i dispositivi restituiti.
  • Per restituire solo i dispositivi presenti nel sistema, impostare il flag di 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 Enumeratore per specificare il GUID o il nome simbolico dell'enumeratore. Se Enumeratore è NULL, SetupDiGetClassDevsEx restituisce i dispositivi per tutti gli enumeratori PnP.

Opzioni di controllo della classe dell'interfaccia del dispositivo

Usare le opzioni di filtro seguenti per controllare se SetupDiGetClassDevsEx restituisce i 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 dispositivo di qualsiasi classe, impostare il flag di DIGCF_DEVICEINTERFACE, impostare il flag di DIGCF_ALLCLASSES e impostare ClassGuid su NULL. La funzione aggiunge alle informazioni sul dispositivo un elemento informazioni dispositivo che rappresenta tale dispositivo e quindi aggiunge all'elemento informazioni del dispositivo un elenco di interfacce 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 alle informazioni sul dispositivo impostare un elemento informazioni dispositivo che rappresenta tale dispositivo e quindi aggiunge un'interfaccia del dispositivo della classe specificata all'elenco delle interfacce del dispositivo per tale elemento informativo del dispositivo.
È inoltre possibile usare le opzioni di filtro seguenti per controllare se SetupDiGetClassDevsEx 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 impostata, per una classe di interfaccia dispositivo specificata, impostare il flag di DIGCF_DEVICEINTERFACE, impostare il flag di DIGCF_DEFAULT e usare ClassGuid per specificare il GUID della classe dell'interfaccia del dispositivo. La funzione aggiunge alle informazioni sul dispositivo impostare un elemento informazioni dispositivo che rappresenta tale dispositivo e quindi aggiunge l'interfaccia predefinita di sistema all'elenco delle interfacce del dispositivo per tale elemento informativo del dispositivo.
  • Per restituire un dispositivo che supporta un'interfaccia predefinita del sistema per una classe di interfaccia del dispositivo non specificata, impostare il flag di DIGCF_DEVICEINTERFACE, impostare il flag di DIGCF_ALLCLASSES, impostare il flag di DIGCF_DEFAULT e impostare ClassGuid su NULL. La funzione aggiunge alle informazioni sul dispositivo impostare un elemento informazioni dispositivo che rappresenta tale dispositivo e quindi aggiunge l'interfaccia predefinita di sistema all'elenco delle interfacce del dispositivo per tale elemento informativo del 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 di 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 di DIGCF_DEVICEINTERFACE e usare il parametro Enumeratore per specificare l'ID istanza del dispositivo del dispositivo. Per includere tutti i dispositivi possibili, impostare Enumerator su NULL.

Recupero di dispositivi in una classe di installazione del dispositivo che supporta una classe dell'interfaccia dispositivo

Un programma di installazione può usare SetupDiGetClassDevsEx per recuperare un elenco di dispositivi di una determinata classe di configurazione del dispositivo che supporta un'interfaccia dispositivo di una classe di interfaccia dispositivo specificata. Ad esempio, per recuperare un elenco di tutti i dispositivi in un computer locale che supporta un'interfaccia del dispositivo nella classe di interfaccia "dispositivo montato" e che sono membri della classe di installazione del dispositivo "Volume", un programma di installazione deve eseguire le operazioni seguenti:
  1. Chiamare SetupDiCreateDeviceInfoList per creare un set di informazioni sul dispositivo vuoto per la classe di installazione del dispositivo "Volume". Impostare ClassGuid su un puntatore al GUID della classe per la classe "Volume" della classe di installazione del dispositivo e impostare hwndParent in base alle esigenze. In risposta a tale chiamata, la funzione restituirà un handle per digitare HDEVINFO al set di informazioni del dispositivo.
  2. Chiamare SetupDiGetClassDevsEx con le impostazioni seguenti:
    • Impostare ClassGuid su un puntatore al GUID della classe della classe dell'interfaccia dispositivo "montata".
    • Impostare Flag su DIGCF_DEVICEINTERFACE.
    • Impostare DeviceInfoSet sull'handle HDEVINFO ottenuto nel passaggio (1).
    • Impostare hwndParent come appropriato e i parametri rimanenti su NULL.
In un'operazione di questo tipo, SetupDiGetClassDevsEx restituisce un dispositivo se la classe di installazione del dispositivo del dispositivo è uguale al set di informazioni del dispositivo fornito e se il dispositivo supporta un'interfaccia del dispositivo la cui classe è uguale alla classe di interfaccia del dispositivo specificata.

Nota

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

Requisiti

Requisito Valore
Client minimo supportato Disponibile in Microsoft Windows 2000 e versioni successive di Windows.
Piattaforma di destinazione Desktop
Intestazione setupapi.h (include Setupapi.h)
Libreria Setupapi.lib

Vedi anche

Set di informazioni sul dispositivo

ID istanza del dispositivo

SetupDiCreateDeviceInfoListEx

SetupDiDestroyDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs