Función UpdateDriverForPlugAndPlayDevicesW (newdev.h)

  • Artículo

Dado un archivo INF y un identificador de hardware, la función UpdateDriverForPlugAndPlayDevices instala controladores actualizados para los dispositivos que coinciden con el identificador de hardware.

Sintaxis

BOOL UpdateDriverForPlugAndPlayDevicesW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR HardwareId,
  [in]            LPCWSTR FullInfPath,
  [in]            DWORD   InstallFlags,
  [out, optional] PBOOL   bRebootRequired
);

Parámetros

[in, optional] hwndParent

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

[in] HardwareId

Puntero a una cadena terminada en NULL que proporciona el identificador de hardware para que coincida con los dispositivos existentes en el equipo. La longitud máxima de un identificador de hardware terminado en NULL es MAX_DEVICE_ID_LEN. Para obtener más información sobre los identificadores de hardware, consulte Cadenas de identificación de dispositivos.

[in] FullInfPath

Puntero a una cadena terminada en NULL que proporciona el nombre de archivo de ruta de acceso completo de un archivo INF. Los archivos deben estar en el medio de distribución o en un directorio creado por el proveedor, no en una ubicación del sistema como %SystemRoot%\inf. UpdateDriverForPlugAndPlayDevices copia los archivos de controlador en las ubicaciones del sistema adecuadas si la instalación se realiza correctamente.

[in] InstallFlags

Valor proporcionado por el autor de la llamada creado mediante OR para combinar cero o más de las marcas de bits siguientes:

INSTALLFLAG_FORCE

Si se establece esta marca y la función busca un dispositivo que coincida con el valor hardwareId , la función instala nuevos controladores para el dispositivo si ya existen controladores mejores en el equipo.

Importante Use esta marca solo con precaución extrema. Establecer esta marca puede hacer que se instale un controlador anterior a través de un controlador más reciente, si un usuario ejecuta la aplicación del proveedor después de que haya controladores más recientes disponibles.
 

INSTALLFLAG_READONLY

Si se establece esta marca, la función no copiará, cambiará el nombre ni eliminará los archivos de instalación. El uso de esta marca debe limitarse a entornos en los que el acceso a archivos está restringido o imposible, como un sistema operativo "incrustado".

INSTALLFLAG_NONINTERACTIVE

Si se establece esta marca, la función devolverá FALSE cuando se detecte cualquier intento de mostrar la interfaz de usuario. Establezca esta marca solo si se llamará a la función desde un componente (como un servicio) que no puede mostrar la interfaz de usuario.

Nota Si se establece esta marca y se intenta mostrar una interfaz de usuario, el dispositivo se puede dejar en un estado indeterminado.
 
El parámetro InstallFlags suele ser cero.

[out, optional] bRebootRequired

Puntero a una variable con tipo BOOL que indica si se requiere un reinicio y quién debe solicitarlo. Este puntero es opcional y puede ser NULL.

Si el puntero es NULL, UpdateDriverForPlugAndPlayDevices solicita un reinicio después de instalar controladores, si es necesario. Si se proporciona el puntero, la función devuelve un valor BOOLEAN que es TRUE si se debe reiniciar el sistema. A continuación, es responsabilidad del autor de la llamada solicitar un reinicio.

Para obtener más información, vea la siguiente sección Comentarios .

Valor devuelto

La función devuelve TRUE si se actualizó un dispositivo al controlador especificado.

De lo contrario, devuelve FALSE y el error registrado se puede recuperar con una llamada a GetLastError. Los posibles valores de error devueltos por GetLastError se incluyen en la tabla siguiente.

Código devuelto Descripción
ERROR_FILE_NOT_FOUND
 La ruta de acceso especificada para FullInfPath no existe.
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.
ERROR_INVALID_FLAGS
 El valor especificado para InstallFlags no es válido.
ERROR_NO_SUCH_DEVINST
 El valor especificado para HardwareId no coincide con ningún dispositivo del sistema. Es decir, el dispositivo no está conectado.
ERROR_NO_MORE_ITEMS
 La función encontró una coincidencia para el valor hardwareId , pero el controlador especificado no era una coincidencia mejor que el controlador actual y el autor de la llamada no especificó la marca INSTALLFLAG_FORCE.

Comentarios

UpdateDriverForPlugAndPlayDevices examina los dispositivos del sistema e intenta instalar los controladores especificados por FullInfPath para todos los dispositivos que coincidan con el valor hardwareId especificado.

El comportamiento predeterminado es instalar solo los controladores especificados si coinciden mejor que los controladores instalados actualmente y los controladores especificados también son una coincidencia mejor que cualquier controlador de %SystemRoot%\inf. Para obtener más información, vea Cómo Selecciona Windows Controladores.

UpdateDriverForPlugAndPlayDevices también se puede usar para determinar si el dispositivo con el valor hardwareId especificado está conectado. Para obtener más información, consulte Escritura de una aplicación de instalación de dispositivos.

UpdateDriverForPlugAndPlayDevices envía una solicitud de IRP_MN_QUERY_REMOVE_DEVICE al dispositivo especificado, todos los elementos secundarios del dispositivo y todos los demás dispositivos que forman parte recursiva de las relaciones de eliminación del dispositivo. Si alguno de estos dispositivos produce un error en una solicitud de eliminación de consulta, UpdateDriverForPlugAndPlayDevices establece la marca DI_NEEDREBOOT en el miembro Flags de la estructura SP_DEVINSTALL_PARAMS para el dispositivo. Para obtener información sobre las relaciones de eliminación, consulte la solicitud de IRP_MN_QUERY_DEVICE_RELATIONS .

Por lo general, las aplicaciones de instalación de dispositivos deben proporcionar NULL para bRebootRequired. Por lo tanto, el sistema iniciará un reinicio si es necesario. Una aplicación debe especificar un valor de puntero solo en los casos siguientes:

  • La aplicación debe llamar a UpdateDriverForPlugAndPlayDevices varias veces para completar una instalación.
  • La aplicación debe realizar otras operaciones antes de que se produzca el reinicio (si es necesario).
  • La aplicación es un instalador de clase, que debe establecer DI_NEEDREBOOT en SP_DEVINSTALL_PARAMS si se necesita un reinicio.
Si la aplicación debe llamar a UpdateDriverForPlugAndPlayDevices varias veces, debe guardar cualquier valor de estado de reinicio TRUE recibido y, a continuación, solicitar un reinicio después de que se haya devuelto la llamada final.

Si la función devuelve ERROR_IN_WOW64 en una aplicación de 32 bits, la aplicación se ejecuta en un sistema de 64 bits, que no se permite. Para obtener más información, consulte Instalación de dispositivos en sistemas de 64 bits.

Requisitos

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