Función SetupDiGetClassDevsExW (setupapi.h)
La función
Sintaxis
WINSETUPAPI HDEVINFO SetupDiGetClassDevsExW(
[in, optional] const GUID *ClassGuid,
[in, optional] PCWSTR Enumerator,
[in, optional] HWND hwndParent,
[in] DWORD Flags,
[in, optional] HDEVINFO DeviceInfoSet,
[in, optional] PCWSTR MachineName,
PVOID Reserved
);
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. 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 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.
Para obtener más información sobre cómo establecer el valor enumerador de
[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 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 o las clases de interfaz de dispositivo especificadas.
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
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
El 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, consulte 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 de NULL para MachineName especifica que el dispositivo está instalado en el equipo local. No se admite el equipo remoto a partir de Windows 8 y Windows Server 2012.
Cautela
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 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 SetupDiGetClassDevsEx debe eliminar la información de dispositivo devuelta cuando ya no sea necesaria llamando 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 del nuevo conjunto de información de dispositivo 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 del dispositivo del conjunto de información del dispositivo proporcionado debe establecerse en el GUID de clase proporcionado.
Opciones de control de clases de configuración de dispositivo
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 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.
- 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 enumerado r de
PnP específico, use el parámetro Enumerador para proporcionar el GUID o el nombre simbólico del enumerador. Sienumerador esNULL ,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 a la información del dispositivo un elemento de información de 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 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.
- 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 de 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 de 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 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, establezcaenumerador enNULL .
recuperar dispositivos en una clase de configuración de dispositivo que admita 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 dispositivos "Volumen", un instalador debe realizar las siguientes operaciones:- Llame a setupDiCreateDeviceInfoList para crear una información de dispositivo vacía establecida para la clase de configuración de dispositivos "Volume". Establezca classGuid en un puntero al GUID de clase para la clase de configuración de 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.
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 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 |
Escritorio |
encabezado de |
setupapi.h (incluya Setupapi.h) |
biblioteca de |
Setupapi.lib |
Consulte también
conjunto de información del dispositivo