Compartir a través de

Función DiInstallDriverW (newdev.h)

  • Artículo

La función DiInstallDriver preinstala un controlador en el almacén de controladores y, a continuación, instala el controlador en los dispositivos presentes en el sistema que admite el controlador.

Sintaxis

BOOL DiInstallDriverW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR InfPath,
  [in]            DWORD   Flags,
  [out, optional] PBOOL   NeedReboot
);

Parámetros

[in, optional] hwndParent

Identificador de la ventana de nivel superior que DiInstallDriver 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] InfPath

Puntero a una cadena terminada en NULL que proporciona la ruta de acceso completa del archivo INF para el paquete de controladores de .

[in] Flags

Valor de tipo DWORD que especifica cero o una combinación de una o varias marcas como se describe aquí (Flags se establece normalmente en cero).

Si flags es cero, DiInstallDriver solo instala el controlador especificado en un dispositivo si el controlador es una coincidencia mejor para un dispositivo que el controlador que está instalado actualmente en un dispositivo. Para obtener información sobre cómo Windows selecciona un controlador para un dispositivo, consulte Cómo Selecciona Windows controladores.

Si marcas incluye DIIRFLAG_FORCE_INF, DiInstallDriver instala el controlador especificado en un dispositivo coincidente tanto si el controlador es una coincidencia mejor para el dispositivo como para el controlador instalado actualmente en el dispositivo. Si también se especifica DIIRFLAG_INSTALL_AS_SET, se omite DIIRFLAG_FORCE_INF.

Precaución Forzar la instalación del controlador puede dar lugar a reemplazar un controlador más compatible o más reciente por un controlador menos compatible o anterior.
 

Si marcas incluye DIIRFLAG_INSTALL_AS_SET (compatibles con windows 10 versión 1709 y posteriores), InfPath debe especificar un directorio en lugar de una ruta de acceso completa a un archivo INF y DiInstallDriver instalará todos los archivos INF en ese directorio con un comportamiento especial. Todos los paquetes de controladores de se almacenarán provisionalmente en la del almacén de controladores de , pero aún no estarán disponibles para instalarse en los dispositivos. En el siguiente apagado del sistema, estos paquetes de controladores estarán disponibles para instalarse en los dispositivos en el futuro y se instalarán en todos los dispositivos que sean la mejor coincidencia para que los dispositivos estén listos para el siguiente arranque del sistema.

[out, optional] NeedReboot

Puntero a un valor de tipo BOOL que DiInstallDriver establece para indicar si se requiere un reinicio del sistema para completar la instalación. Este parámetro es opcional y se puede NULL. Si se proporciona el parámetro y se requiere un reinicio del sistema para completar la instalación, DiInstallDriver establece el valor en TRUE. En este caso, el autor de la llamada debe pedir al usuario que reinicie el sistema. Si se proporciona este parámetro y no es necesario reiniciar el sistema para completar la instalación, DiInstallDriver establece el valor en FALSE. Si el parámetro es NULL y se requiere un reinicio del sistema para completar la instalación, DiInstallDriver muestra un cuadro de diálogo de reinicio del sistema. Para obtener más información sobre este parámetro, consulte la siguiente sección Comentarios.

Valor devuelto

DiInstallDriver devuelve TRUE si la función preinstaló correctamente el paquete de controladores de especificado en el almacén de controladores de . DiInstallDriver también devuelve TRUE si la función instaló correctamente el controlador en uno o varios dispositivos del sistema. Si el paquete de controladores no está instalado correctamente en el almacén de controladores, DiInstallDriver devuelve FALSE y se puede recuperar el error registrado realizando una llamada a GetLastError. Algunos de los valores de error más comunes que GetLastError pueden 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 requiere que el autor de la llamada tenga privilegios de administrador para preinstalar un paquete de controladores de en el almacén de controladores de .
ERROR_FILE_NOT_FOUND
 La ruta de acceso del archivo INF especificado no existe.
ERROR_INVALID_FLAGS
 El valor especificado para flags no es igual a cero o DIIRFLAG_FORCE_INF.
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.

Observaciones

diInstallDriver realiza las siguientes operaciones:

  1. Preinstala el paquete de controladores de en el almacén de controladores de . Si hay una instancia del mismo paquete de controladores ya preinstalado en el almacén de controladores, DiInstallDriver primero quita esa instancia y, a continuación, agrega la nueva instancia del paquete de controladores al almacén de controladores.
  2. Enumera los dispositivos que están presentes en el sistema.
  3. Si marcas es igual a cero, instala el controlador en un dispositivo solo si el controlador especificado es una coincidencia mejor para el dispositivo que el controlador que está instalado actualmente en el dispositivo.
  4. Si marcas es igual a DIIRFLAG_FORCE_INF, instala el controlador en un dispositivo independientemente de si el paquete de controladores es la mejor coincidencia con el dispositivo que el controlador que está instalado actualmente en el dispositivo.
En general, una aplicación de instalación debe establecer NeedReboot en NULL para dirigir DiInstallDriver para pedir 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 DiInstallDriver varias veces para completar una instalación. En este caso, la aplicación debe registrar si una TRUENeedReboot valor se devuelve mediante cualquiera de las llamadas a DiInstallDriver y, si es así, pide al usuario que reinicie el sistema después de la llamada final a DiInstallDriver devuelve.
  • La aplicación debe realizar operaciones necesarias, aparte de llamar a DiInstallDriver, 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 de DI_NEEDREBOOT en el Flags miembro de la estructura de SP_DEVINSTALL_PARAMS para un dispositivo.
Para instalar un controlador seleccionado en un dispositivo seleccionado, llame a DiInstallDevice. Para obtener más información, consulta Funciones setupAPI que simplifican la instalación de controladores.

Nota

El encabezado newdev.h define DiInstallDriver 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 Windows Vista y versiones posteriores de Windows.
de la plataforma de destino de Escritorio
encabezado de newdev.h (incluya Newdev.h)
biblioteca de Newdev.lib

Consulte también

DiInstallDevice