Función DiInstallDriverA (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 DiInstallDriverA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR 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.

[in] Flags

Valor de tipo DWORD que especifica cero o una combinación de una o varias marcas, tal y como se describe aquí (Normalmente, las marcas se establecen 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, vea Cómo selecciona Windows Controladores.

Si Flags incluye DIIRFLAG_FORCE_INF, DiInstallDriver instala el controlador especificado en un dispositivo coincidente, independientemente de si el controlador es una coincidencia mejor para el dispositivo que el controlador que está 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 Flags incluye DIIRFLAG_INSTALL_AS_SET (compatible 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 se almacenarán provisionalmente en el almacén de controladores , pero aún no estarán disponibles para instalarse en los dispositivos. En el próximo 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 en 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 puede ser 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, vea la siguiente sección Comentarios .

Valor devuelto

DiInstallDriver devuelve TRUE si la función preinstala correctamente el paquete de controladores especificado en el almacén de controladores. 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 el error registrado se puede recuperar mediante la 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 requiere que el autor de la llamada tenga privilegios de administrador para preinstalar un paquete de controladores en el almacén de controladores.
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.

Comentarios

DiInstallDriver realiza las siguientes operaciones:

  1. Preinstala el paquete de controladores en el almacén de controladores. 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 Flags 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 Flags 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 a 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 alguna de las llamadas a DiInstallDriver devuelve un valor TRUE NeedReboot y, si es así, solicitar al usuario que reinicie el sistema después de la llamada final a DiInstallDriver devuelve.
  • La aplicación debe realizar operaciones necesarias, excepto 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 DI_NEEDREBOOT en el miembro Flags de la estructura SP_DEVINSTALL_PARAMS de un dispositivo.
Para instalar un controlador seleccionado en un dispositivo seleccionado, llame a DiInstallDevice. Para obtener más información, vea Funciones setupAPI que simplifican la instalación del controlador.

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 Convenciones para prototipos de función.

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

Consulte también

DiInstallDevice