Función DiInstallDevice (newdev.h)

Artículo
03/08/2023

La función DiInstallDevice instala un controlador especificado que está preinstalado en el almacén de controladores en un dispositivo especificado que está presente en el sistema.

Sintaxis

BOOL DiInstallDevice(
  [in, optional]  HWND             hwndParent,
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in, optional]  PSP_DRVINFO_DATA DriverInfoData,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

Parámetros

[in, optional] hwndParent

Identificador de la ventana de nivel superior que DiInstallDevice usa para mostrar cualquier componente de interfaz de usuario asociado a la instalación del dispositivo. Este parámetro es opcional y se puede establecer en NULL.

[in] DeviceInfoSet

Identificador de un conjunto de información de dispositivo que contiene un elemento de información del dispositivo que representa el dispositivo especificado.

[in] DeviceInfoData

Puntero a una estructura de SP_DEVINFO_DATA que representa el dispositivo especificado en el conjunto de información del dispositivo especificado.

[in, optional] DriverInfoData

Puntero a una estructura de SP_DRVINFO_DATA que especifica el controlador que se va a instalar en el dispositivo especificado. Este parámetro es opcional y se puede establecer en NULL. Si este parámetro es NULL, DiInstallDevice busca los controladores preinstalados en el almacén de controladores para el controlador que es la mejor coincidencia con el dispositivo especificado y, si se encuentra, instala el controlador en el dispositivo especificado.

[in] Flags

Valor de tipo DWORD que especifica cero o la marca siguiente:

DIIDFLAG_SHOWSEARCHUI

Si el autor de la llamada no especifica un controlador (DriverInfoData está establecido en NULL) y DiInstallDevice no busca un controlador preinstalado que coincida con el dispositivo especificado. En su lugar, DiInstallDevice muestra el Asistente para nuevo hardware encontrado para el dispositivo.

DIIDFLAG_NOFINISHINSTALLUI

DiInstallDevice no inicia las páginas del asistente para finalizar la instalación ni las acciones de instalación de fin. El autor de la llamada de DiInstallDevice debe iniciar estas operaciones. El autor de la llamada solo debe especificar esta marca si el autor de la llamada requiere que se invoquen las páginas del asistente para finalizar la instalación en el contexto de un componente de interfaz de usuario proporcionado por el autor de la llamada.

DIIDFLAG_INSTALLNULLDRIVER

DiInstallDevice intenta instalar un controlador NULL en el dispositivo especificado. Si se establece esta marca, DiInstallDevice no usa el parámetro DriverInfoData . DiInstallDevice quita toda la configuración del dispositivo y, si el dispositivo no se puede ejecutar en modo sin procesar, la función establece el estado del dispositivo en CM_PROB_FAILED_INSTALL. Si DiInstallDevice no puede instalar un controlador NULL, el estado resultante del dispositivo es el mismo que si el dispositivo se conectó por primera vez al equipo y Windows no encontró un controlador para el dispositivo.

DIIDFLAG_INSTALLCOPYINFDRIVERS

Cualquier archivo INF adicional especificado a través de una directiva CopyINF se instalará en cualquier dispositivo al que sea aplicable. Cualquier error al instalar un INF adicional no hará que se produzca un error en la instalación de INF principal.

[out, optional] NeedReboot

Puntero a un valor de tipo BOOL que DiInstallDevice establece para indicar si se requiere un reinicio del sistema para completar la instalación. Este parámetro es opcional y se puede establecer en NULL. Si se proporciona este parámetro y se requiere un reinicio del sistema para completar la instalación, DiInstallDevice establece el valor en TRUE. En este caso, el autor de la llamada es responsable de reiniciar el sistema. Si se proporciona este parámetro y no se requiere un reinicio del sistema, DiInstallDevice establece este parámetro en FALSE. Si este parámetro es NULL y se requiere un reinicio del sistema para completar la instalación, DiInstallDevice muestra un cuadro de diálogo de reinicio del sistema.

Valor devuelto

DiInstallDevice devuelve TRUE si la función instaló correctamente el controlador especificado en el dispositivo especificado. De lo contrario, DiInstallDevice devuelve FALSE y el error registrado se puede recuperar realizando una llamada a GetLastError. Algunos de los valores de error más comunes que GetLastError podrían devolver son los siguientes:

Código devuelto	Descripción
ERROR_ACCESS_DENIED	El autor de la llamada no tiene privilegios de administrador. De forma predeterminada, Windows Vista y Windows Server 2008 requieren que un proceso de llamada tenga privilegios de administrador para instalar un controlador en un dispositivo.
ERROR_INVALID_FLAGS	El valor especificado para Flags no es cero o un OR bit a bit de las marcas válidas.
ERROR_IN_WOW64	La aplicación que realiza la llamada es una aplicación de 32 bits que intenta ejecutarse en un entorno de 64 bits, que no está permitido. Para obtener más información, consulte Instalación de dispositivos en sistemas de 64 bits.

Comentarios

Llame solo a DiInstallDevice si es necesario instalar un controlador específico en un dispositivo específico. De lo contrario, use UpdateDriverForPlugAndPlayDevices o DiInstallDriver para instalar un controlador para un dispositivo. Para obtener más información sobre cuál de estas funciones llamar para instalar un controlador en un dispositivo, consulte SetupAPI Functions that Simplify Driver Installation.

Antes de llamar a DiInstallDevice, el autor de la llamada debe obtener una estructura de SP_DEVINFO_DATA para especificar el dispositivo y, opcionalmente, una estructura de SP_DRVINFO_DATA para especificar un controlador para el dispositivo.

Para crear un conjunto de información de dispositivo que contenga el dispositivo especificado y para obtener una estructura de SP_DEVINFO_DATA para el dispositivo, realice una de las acciones siguientes:

Llame a SetupDiGetClassDevs para recuperar un conjunto de información del dispositivo que contiene el dispositivo y, a continuación, llame a SetupDiEnumDeviceInfo para enumerar los dispositivos del conjunto de información del dispositivo. En cada llamada, SetupDiEnumDeviceInfo devuelve una estructura SP_DEVINFO_DATA que representa el dispositivo enumerado en el conjunto de información del dispositivo. Para obtener información específica sobre el dispositivo enumerado, llame a SetupDiGetDeviceProperty y proporcione la estructura SP_DEVINFO_DATA devuelta por SetupDiEnumDeviceInfo.
- O BIEN
Llame a SetupDiOpenDeviceInfo para agregar un dispositivo con un identificador de instancia de dispositivo conocido al conjunto de información del dispositivo. SetupDiOpenDeviceInfo devuelve una estructura SP_DEVINFO_DATA que representa el dispositivo en el conjunto de información del dispositivo.

Para recuperar una estructura de SP_DRVINFO_DATA para un controlador seleccionado, llame a SetupDiBuildDriverInfoList para compilar una lista de controladores para el dispositivo y, a continuación, llame a SetupDiEnumDriverInfo para enumerar los elementos de la lista de controladores del dispositivo. Para cada controlador enumerado, SetupDiEnumDriverInfo recupera una estructura de SP_DRVINFO_DATA que identifica el controlador. También se puede llamar a SetupDiGetDriverInfoDetail para recuperar detalles adicionales sobre un controlador enumerado.

En general, una aplicación de instalación debe establecer NeedReboot en NULL. Esto garantiza que DiInstallDevice pida al usuario que reinicie el sistema si se requiere un reinicio para completar la instalación. Una aplicación debe proporcionar un puntero NeedReboot solo en los casos siguientes:

La aplicación debe llamar a DiInstallDevice varias veces para completar una instalación. En este caso, la aplicación debe registrar si alguna de las llamadas a DiInstallDevice devuelve un valor TRUE NeedReboot y, si es así, pide al usuario que reinicie el sistema después de la llamada final a DiInstallDevice.
La aplicación debe realizar operaciones necesarias, aparte de llamar a DiInstallDevice, antes de que se produzca un reinicio del sistema. Si se requiere un reinicio del sistema, la aplicación debe finalizar las operaciones necesarias y, a continuación, pedir al usuario que reinicie el sistema.
La aplicación es un instalador de clase, en cuyo caso, el instalador de clase debe establecer la marca DI_NEEDREBOOT en el miembro Flags de la estructura SP_DEVINSTALL_PARAMS para un dispositivo.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores de Windows.
Plataforma de destino	Escritorio
Encabezado	newdev.h (incluya Newdev.h)
Library	Newdev.lib
Archivo DLL	Newdev.dll