Función SetupDiGetClassDevsExA (setupapi.h)

Artículo
03/15/2023

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

Sintaxis

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

Parámetros

[in, optional] 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. Si no se usa un valor GUID para seleccionar dispositivos, establezca ClassGuid en NULL. Para obtener más información sobre cómo usar ClassGuid, vea la siguiente sección Comentarios .

[in, optional] 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 enumerador o el nombre simbólico. Por ejemplo, se puede usar "PCI" para especificar el enumerador PnP de PCI. Otros ejemplos de nombres simbólicos para enumeradores PnP incluyen "USB", "PCMCIA" y "SCSI".
Identificadores 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 Enumerador 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 .

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

[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 una o varias de las marcas siguientes. Para obtener más información sobre cómo combinar estas opciones de control, vea la siguiente sección Comentarios .

DIGCF_ALLCLASSES

Devuelve una lista de dispositivos instalados para las clases de configuración de dispositivos especificadas o 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 Enumerator 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.

DIGCF_PROFILE

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

[in, optional] DeviceInfoSet

Identificador de un conjunto de información de dispositivo existente al que SetupDiGetClassDevsEx agrega los elementos de información del dispositivo solicitados. Este parámetro es opcional y se puede establecer en NULL. Para obtener más información sobre el uso de este parámetro, vea la siguiente sección Comentarios .

[in, optional] MachineName

Puntero a una cadena constante que contiene el nombre de un equipo remoto en el que residen los dispositivos. Un valor null paraMachineName especifica que el dispositivo está instalado en el equipo local.

Precaución

No se admite el uso de esta función para acceder a máquinas remotas a partir de Windows 8 y Windows Server 2012, ya que esta funcionalidad se ha quitado.

Reserved

Reservado para uso interno. Este parámetro debe establecerse en NULL.

Valor devuelto

Si la operación se realiza correctamente, SetupDiGetClassDevsEx 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 autor de la llamada de SetupDiGetClassDevsEx debe eliminar la información de dispositivo devuelta establecida cuando ya no sea necesaria mediante una llamada a SetupDiDestroyDeviceInfoList.

Si DeviceInfoSet es NULL, SetupDiGetClassDevsEx crea un nuevo conjunto de información de dispositivo que contiene los elementos de información del dispositivo recuperados y devuelve un identificador al nuevo conjunto de información del dispositivo. Si el autor de la llamada solicita que la función recupere dispositivos para una clase de configuración de dispositivo proporcionada por el parámetro ClassGuid , la función establece la clase de configuración del dispositivo de la nueva información del dispositivo establecida en el GUID de clase proporcionado.

Si DeviceInfoSet no está establecido en NULL, la función agrega los elementos de información del dispositivo recuperados al conjunto de información del dispositivo asociado al identificador proporcionado y devuelve el identificador proporcionado. Si ClassGuid proporciona una clase de configuración de dispositivo, la clase de configuración de dispositivo del conjunto de información de dispositivo proporcionado debe establecerse en el GUID de clase proporcionado.

Opciones de control de clase de configuración de dispositivos

Use las siguientes opciones de filtrado para controlar si SetupDiGetClassDevsEx devuelve dispositivos para todas las clases de configuración de dispositivos o solo para una clase de instalació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 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 Enumerador es NULL, SetupDiGetClassDevsEx 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 SetupDiGetClassDevsEx 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 al conjunto de información del dispositivo un elemento de información del dispositivo que representa dicho 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 al conjunto de información del dispositivo un elemento de información del 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 SetupDiGetClassDevsEx 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 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 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 al conjunto de 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 los dispositivos que 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.

Recuperación de dispositivos en una clase de configuración de dispositivo que admite una clase de interfaz de dispositivo

Un instalador puede usar SetupDiGetClassDevsEx para recuperar una lista de dispositivos de una clase de configuración de dispositivo determinada que admita una interfaz de dispositivo de una clase de interfaz de dispositivo especificada. Por ejemplo, para recuperar una lista de todos los dispositivos de un equipo local que admiten una interfaz de dispositivo en la clase de interfaz "dispositivo montado" y que son miembros de la clase de configuración de dispositivo "Volumen", un instalador debe realizar las siguientes operaciones:

Llame a SetupDiCreateDeviceInfoList para crear un conjunto de información de dispositivo vacío para la clase de configuración del dispositivo "Volume". Establezca ClassGuid en un puntero al GUID de clase para la clase de instalación del dispositivo "Volume" y establezca hwndParent según corresponda. En respuesta a esta llamada, la función devolverá un identificador para escribir HDEVINFO en el conjunto de información del dispositivo.
Llame a SetupDiGetClassDevsEx con la siguiente configuración:
- Establezca ClassGuid en un puntero al GUID de clase de la clase de interfaz de dispositivo "dispositivo montado".
- Establezca Marcas en DIGCF_DEVICEINTERFACE.
- Establezca DeviceInfoSet en el identificador HDEVINFO obtenido en el paso (1).
- Establezca hwndParent según corresponda y los parámetros restantes en NULL.

En una operación de este tipo, SetupDiGetClassDevsEx devuelve un dispositivo si la clase de configuración de dispositivo del dispositivo es la misma que el conjunto de información del dispositivo proporcionado y si el dispositivo admite una interfaz de dispositivo cuya clase es la misma que la clase de interfaz de dispositivo especificada.

Nota

El encabezado setupapi.h define SetupDiGetClassDevsEx 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 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	Escritorio
Encabezado	setupapi.h (incluya Setupapi.h)
Library	Setupapi.lib