Función SetupDiGetClassDevsW (setupapi.h)

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 SetupDiGetClassDevsW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCWSTR     Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags
);

Parámetros

[in, optional] ClassGuid

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

[in, optional] Enumerator

Puntero a una cadena terminada en NULL que especifica:

• Identificador (ID) de un enumerador 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".
• Un 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 se puede 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 enumerador de , consulte la siguiente sección Comentarios.

[in, optional] hwndParent

Identificador de la ventana de nivel superior que se va a 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 se puede NULL.

[in] 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, consulte 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 de 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 de 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.

Observaciones

El autor de la llamada de SetupDiGetClassDevs debe eliminar la información de dispositivo devuelta cuando ya no sea 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 dispositivo

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 de PnP específico, use el parámetro enumerador de para proporcionar el GUID o el nombre simbólico del enumerador. Si enumerador es NULL, SetupDiGetClassDevs devuelve dispositivos para todos los enumeradores PnP.

Opciones de control de clase 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 DIGCF_ALLCLASSES y establezca ClassGuid en NULL. La función agrega a la 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 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 a la información del dispositivo un elemento de información del dispositivo que representa dicho 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 DIGCF_DEFAULT y establezca ClassGuid en NULL. La función agrega a la información del dispositivo un elemento de información del dispositivo que representa dicho 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 de 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: Crear una lista de todos los dispositivos del sistema, incluidos los dispositivos que no están presentes actualmente.

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

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

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

ejemplo 3: Crear una lista de todos los dispositivos presentes en el sistema que proceden del adaptador de red clase de configuración de dispositivos.

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

Ejemplo 4: Crear una lista de todos los dispositivos presentes en el sistema que han habilitado una interfaz desde el volumen de almacenamiento clase de interfaz de dispositivo.

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

ejemplo 5: Compilar una lista de todos los dispositivos que están presentes en el sistema, pero que no pertenecen a ninguna clase de configuració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 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible en Microsoft Windows 2000 y versiones posteriores de Windows.
de la plataforma de destino de	DesktopFor universal, call CM_Get_Device_ID_ListFor universal, call CM_Get_Device_Interface_List
encabezado de	setupapi.h (incluya SetupAPI.h)
biblioteca de	SetupAPI.lib
DLL de	SetupAPI.dll
conjunto de API de	ext-ms-win-setupapi-classinstallers-l1-1-0 (introducido en Windows 8)

Consulte también

conjunto de información del dispositivo

identificadores de instancia de dispositivo

setupDiCreateDeviceInfoList

SetupDiDestroyDeviceInfoList

setupDiEnumDeviceInterfaces

SetupDiGetClassDevsEx