Función SetupDiOpenDeviceInfoW (setupapi.h)

Artículo
03/15/2023

La función SetupDiOpenDeviceInfo agrega un elemento de información del dispositivo para una instancia de dispositivo a un conjunto de información del dispositivo, si aún no existe en el conjunto de información del dispositivo y recupera información que identifica el elemento de información del dispositivo para la instancia del dispositivo en el conjunto de información del dispositivo.

Sintaxis

WINSETUPAPI BOOL SetupDiOpenDeviceInfoW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCWSTR           DeviceInstanceId,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            OpenFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

Parámetros

[in] DeviceInfoSet

Identificador de la información del dispositivo establecida en la que SetupDiOpenDeviceInfo agrega un elemento de información del dispositivo, si aún no existe, para la instancia de dispositivo especificada por DeviceInstanceId.

[in] DeviceInstanceId

Puntero a una cadena terminada en NULL que proporciona el identificador de instancia de dispositivo de un dispositivo (por ejemplo, "Root*PNP0500\0000"). Si DeviceInstanceId es NULL o hace referencia a una cadena de longitud cero, SetupDiOpenDeviceInfo agrega un elemento de información del dispositivo al conjunto de información del dispositivo proporcionado, si aún no existe alguno, para el dispositivo raíz en el árbol de dispositivos.

[in, optional] hwndParent

Identificador de la ventana de nivel superior que se usará para cualquier interfaz de usuario relacionada con la instalación del dispositivo.

[in] OpenFlags

Variable de tipo DWORD que controla cómo se abre el elemento de información del dispositivo. El valor de este parámetro puede ser uno o varios de los siguientes:

DIOD_CANCEL_REMOVE

Si se especifica esta marca y el dispositivo se ha marcado para la eliminación pendiente, el sistema operativo cancela la eliminación pendiente.

DIOD_INHERIT_CLASSDRVS

Si se especifica esta marca, el elemento de información del dispositivo resultante hereda la lista de controladores de clase, si existe, asociada al conjunto de información del dispositivo. Además, si hay un controlador seleccionado para el conjunto de información del dispositivo, ese mismo controlador se selecciona para el nuevo elemento de información del dispositivo.

Si el elemento de información del dispositivo ya estaba presente, su lista de controladores de clase, si existe, se reemplaza por la lista heredada.

[out, optional] DeviceInfoData

Puntero a una estructura de SP_DEVINFO_DATA proporcionada por el autor de la llamada que recibe información sobre el elemento de información del dispositivo para la instancia de dispositivo especificada por DeviceInstanceId. El autor de la llamada debe establecer cbSize en sizeof(SP_DEVINFO_DATA). Este parámetro es opcional y puede ser NULL.

Valor devuelto

SetupDiOpenDeviceInfo devuelve TRUE si se realiza correctamente. De lo contrario, la función devuelve FALSE y el error registrado se puede recuperar con una llamada a GetLastError.

Comentarios

Si esta instancia de dispositivo se agrega a un conjunto que tiene una clase asociada, la clase de dispositivo debe ser la misma o se producirá un error en la llamada. En este caso, una llamada a GetLastError devuelve ERROR_CLASS_MISMATCH.

Si el nuevo elemento de información del dispositivo se abre correctamente, pero el búfer DeviceInfoData proporcionado por el autor de la llamada no es válido, esta función devuelve FALSE. En este caso, una llamada a GetLastError devuelve ERROR_INVALID_USER_BUFFER. Sin embargo, el elemento de información del dispositivo se agrega como un nuevo miembro del conjunto de todos modos.

Nota

El encabezado setupapi.h define SetupDiOpenDeviceInfo 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
Conjunto de API	ext-ms-win-setupapi-classinstallers-l1-1-1 (introducido en Windows 8.1)