Share via

Función SetupDiGetClassDevsA (setupapi.h)

  • Artículo

La función SetupDiGetClassDevs devuelve un identificador a un conjunto de información de dispositivo que contiene elementos de información de dispositivo solicitados para un equipo local.

Sintaxis

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

Parámetros

ClassGuid

Puntero al GUID de una clase de configuración de dispositivo o una clase de interfaz de dispositivo. Este puntero es opcional y puede ser NULL. Para obtener más información sobre cómo establecer ClassGuid, vea la siguiente sección Comentarios .

Enumerator

Puntero a una cadena terminada en NULL que especifica:

  • Identificador (ID) de un enumerador de Plug and Play (PnP). Este identificador puede ser el identificador único global (GUID) del valor o el nombre simbólico. Por ejemplo, se puede usar "PCI" para especificar el valor PnP de PCI. Otros ejemplos de nombres simbólicos para los valores PnP incluyen "USB", "PCMCIA" y "SCSI".
  • Identificador de instancia de dispositivo PnP. Al especificar un identificador de instancia de dispositivo PnP, DIGCF_DEVICEINTERFACE debe establecerse en el parámetro Flags.
Este puntero es opcional y puede ser NULL. Si no se usa un valor de enumeración para seleccionar dispositivos, establezca Enumerador en NULL.

Para obtener más información sobre cómo establecer el valor del enumerador , vea la siguiente sección Comentarios .

hwndParent

Identificador de la ventana de nivel superior que se usará para una interfaz de usuario asociada a la instalación de una instancia de dispositivo en el conjunto de información del dispositivo. Este identificador es opcional y puede ser NULL.

Flags

Variable de tipo DWORD que especifica las opciones de control que filtran los elementos de información del dispositivo que se agregan al conjunto de información del dispositivo. Este parámetro puede ser un OR bit a bit de cero o más de las marcas siguientes. Para obtener más información sobre cómo combinar estas marcas, vea la siguiente sección Comentarios .

DIGCF_ALLCLASSES

Devuelve una lista de dispositivos instalados para todas las clases de configuración de dispositivos o todas las clases de interfaz de dispositivo.

DIGCF_DEVICEINTERFACE

Devuelve dispositivos que admiten interfaces de dispositivo para las clases de interfaz de dispositivo especificadas. Esta marca debe establecerse en el parámetro Flags si el parámetro Enumerador especifica un identificador de instancia de dispositivo.

DIGCF_DEFAULT

Devuelve solo el dispositivo asociado a la interfaz de dispositivo predeterminada del sistema, si se establece uno, para las clases de interfaz de dispositivo especificadas.

DIGCF_PRESENT

Devuelve solo los dispositivos que están presentes actualmente en un sistema.

DIGCF_PROFILE

Devuelve solo los dispositivos que forman parte del perfil de hardware actual.

Valor devuelto

Si la operación se realiza correctamente, SetupDiGetClassDevs devuelve un identificador a un conjunto de información del dispositivo que contiene todos los dispositivos instalados que coinciden con los parámetros proporcionados. Si se produce un error en la operación, la función devuelve INVALID_HANDLE_VALUE. Para obtener información de error extendida, llame a GetLastError.

Comentarios

El llamador de SetupDiGetClassDevs debe eliminar la información de dispositivo devuelta establecida cuando ya no es necesaria llamando a SetupDiDestroyDeviceInfoList.

Llame a SetupDiGetClassDevsEx para recuperar los dispositivos de una clase en un equipo remoto.

Opciones de control de clases de configuración de dispositivos

Use las siguientes opciones de filtrado para controlar si SetupDiGetClassDevs devuelve dispositivos para todas las clases de configuración de dispositivos o solo para una clase de configuración de dispositivo especificada:
  • Para devolver dispositivos para todas las clases de configuración de dispositivos, establezca la marca DIGCF_ALLCLASSES y establezca el parámetro ClassGuid en NULL.
  • Para devolver dispositivos solo para una clase de configuración de dispositivo específica, no establezca DIGCF_ALLCLASSES y use ClassGuid para proporcionar el GUID de la clase de configuración del dispositivo.
Además, puede usar las siguientes opciones de filtrado en combinación entre sí para restringir aún más qué dispositivos se devuelven:
  • Para devolver solo los dispositivos que están presentes en el sistema, establezca la marca DIGCF_PRESENT.
  • Para devolver solo los dispositivos que forman parte del perfil de hardware actual, establezca la marca DIGCF_PROFILE.
  • Para devolver dispositivos solo para un enumerador PnP específico, use el parámetro Enumerador para proporcionar el GUID o el nombre simbólico del enumerador. Si El enumerador es NULL, SetupDiGetClassDevs devuelve dispositivos para todos los enumeradores PnP.

Opciones de control de clases de interfaz de dispositivo

Use las siguientes opciones de filtrado para controlar si SetupDiGetClassDevs devuelve dispositivos que admiten cualquier clase de interfaz de dispositivo o solo dispositivos que admiten una clase de interfaz de dispositivo especificada:
  • Para devolver dispositivos que admiten una interfaz de dispositivo de cualquier clase, establezca la marca DIGCF_DEVICEINTERFACE, establezca la marca de DIGCF_ALLCLASSES y establezca ClassGuid en NULL. La función agrega al conjunto de información del dispositivo un elemento de información de dispositivo que representa este dispositivo y, a continuación, agrega al elemento de información del dispositivo una lista de interfaz de dispositivo que contiene todas las interfaces de dispositivo que admite el dispositivo.
  • Para devolver solo los dispositivos que admiten una interfaz de dispositivo de una clase especificada, establezca la marca DIGCF_DEVICEINTERFACE y use el parámetro ClassGuid para proporcionar el GUID de clase de la clase de interfaz de dispositivo. La función agrega a la información del dispositivo un elemento de información de dispositivo que representa dicho dispositivo y, a continuación, agrega una interfaz de dispositivo de la clase especificada a la lista de interfaz de dispositivo para ese elemento de información del dispositivo.
Además, puede usar las siguientes opciones de filtrado para controlar si SetupDiGetClassDevs devuelve solo los dispositivos que admiten la interfaz predeterminada del sistema para las clases de interfaz de dispositivo:
  • Para devolver solo el dispositivo que admite la interfaz predeterminada del sistema, si se establece uno, para una clase de interfaz de dispositivo especificada, establezca la marca de DIGCF_DEVICEINTERFACE, establezca la marca de DIGCF_DEFAULT y use ClassGuid para proporcionar el GUID de clase de la clase de interfaz de dispositivo. La función agrega al conjunto de información del dispositivo un elemento de información de dispositivo que representa este dispositivo y, a continuación, agrega la interfaz predeterminada del sistema a la lista de interfaz de dispositivo para ese elemento de información del dispositivo.
  • Para devolver un dispositivo que admita una interfaz predeterminada del sistema para una clase de interfaz de dispositivo no especificada, establezca la marca DIGCF_DEVICEINTERFACE, establezca la marca DIGCF_ALLCLASSES, establezca la marca de DIGCF_DEFAULT y establezca ClassGuid en NULL. La función agrega al conjunto de información del dispositivo un elemento de información de dispositivo que representa este dispositivo y, a continuación, agrega la interfaz predeterminada del sistema a la lista de interfaz de dispositivo para ese elemento de información del dispositivo.
También puede usar las siguientes opciones en combinación con las otras opciones para restringir aún más qué dispositivos se devuelven:
  • Para devolver solo los dispositivos que están presentes en el sistema, establezca la marca DIGCF_PRESENT.
  • Para devolver solo los dispositivos que forman parte del perfil de hardware actual, establezca la marca DIGCF_PROFILE.
  • Para devolver solo un dispositivo específico, establezca la marca DIGCF_DEVICEINTERFACE y use el parámetro Enumerador para proporcionar el identificador de instancia de dispositivo del dispositivo. Para incluir todos los dispositivos posibles, establezca Enumerador en NULL.

Ejemplos

A continuación se muestran algunos ejemplos de cómo usar la función SetupDiGetClassDevs .

Ejemplo 1: Cree una lista de todos los dispositivos del sistema, incluidos los que no están presentes actualmente.

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

Ejemplo 2: Cree una lista de todos los dispositivos que están presentes en el sistema.

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

Ejemplo 3: Cree una lista de todos los dispositivos que están presentes en el sistema que proceden de la clase de configuración de dispositivos del adaptador de red.

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

Ejemplo 4: Cree una lista de todos los dispositivos que están presentes en el sistema que han habilitado una interfaz desde la clase de interfaz de dispositivo de volumen de almacenamiento.

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

Ejemplo 5: Compile una lista de todos los dispositivos que están presentes en el sistema, pero que no pertenezcan a ninguna clase de instalación de dispositivo conocida (Windows Vista y versiones posteriores de Windows).

Nota No se puede establecer el parámetro ClassGuid en GUID_DEVCLASS_UNKNOWN para detectar dispositivos con una clase de instalación desconocida. En su lugar, debe seguir este ejemplo.
 
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

El encabezado setupapi.h define SetupDiGetClassDevs como un alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito Value
Cliente mínimo compatible Disponible en Microsoft Windows 2000 y versiones posteriores de Windows.
Plataforma de destino DesktopFor universal, call CM_Get_Device_ID_ListFor universal, call CM_Get_Device_Interface_List
Encabezado setupapi.h (incluya SetupAPI.h)
Library SetupAPI.lib
Archivo DLL SetupAPI.dll
Conjunto de API ext-ms-win-setupapi-classinstallers-l1-1-2 (introducido en Windows 10, versión 10.0.14393)

Consulte también

Conjunto de información del dispositivo

Identificadores de instancia de dispositivo

SetupDiCreateDeviceInfoList

SetupDiDestroyDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevsEx