Given an INF file and a hardware ID, the UpdateDriverForPlugAndPlayDevices function installs updated drivers for devices that match the hardware ID.

BOOL WINAPI
  UpdateDriverForPlugAndPlayDevices(
    IN HWND  hwndParent  OPTIONAL,
    IN LPCTSTR  HardwareId,
    IN LPCTSTR  FullInfPath,
    IN DWORD  InstallFlags,
    OUT PBOOL  bRebootRequired  OPTIONAL
    );

Parameters

hwndParent

A handle to the top-level window to use for any UI related to installing devices.

HardwareId

A pointer to a NULL-terminated string that supplies the hardware identifier to match existing devices on the computer. The maximum length of a NULL-terminated hardware identifier is MAX_DEVICE_ID_LEN. For more information about hardware identifiers, see Device Identification Strings.

FullInfPath

A pointer to a NULL-terminated string that supplies the full path of an INF file and any associated driver files. The files should be on the distribution media or in a vendor-created directory, not in a system location such as %SystemRoot%\inf. UpdateDriverForPlugAndPlayDevices copies driver files to the appropriate system locations if the installation is successful.

InstallFlags

A caller-supplied value created by ORing zero or more for the following bit flags:

INSTALLFLAG_FORCE

If this flag is set and the function finds a device that matches the HardwareId value, the function installs new drivers for the device whether better drivers already exist on the computer.

Important  Use this flag only with extreme caution. Setting this flag can cause an older driver to be installed over a newer driver, if a user runs the vendor's application after newer drivers are available.

INSTALLFLAG_READONLY

If this flag is set, the function will not copy, rename, or delete any installation files. Use of this flag should be limited to environments in which file access is restricted or impossible, such as an "embedded" operating system.

INSTALLFLAG_NONINTERACTIVE

If this flag is set, the function will return FALSE when any attempt to display UI is detected. Set this flag only if the function will be called from a component (such as a service) that cannot display UI.

Note  If this flag is set and a UI display is attempted, the device can be left in an indeterminate state.

The InstallFlags parameter is typically zero.

bRebootRequired

A pointer to a BOOL-typed variable that indicates whether a restart is required and who should prompt for it. This pointer is optional and can be NULL.

If the pointer is NULL, UpdateDriverForPlugAndPlayDevices prompts for a restart after installing drivers, if necessary. If the pointer is supplied, the function returns a BOOLEAN value that is TRUE if the system should be restarted. It is then the caller's responsibility to prompt for a restart.

For more information, see the following Comments section.

Return Value

The function returns TRUE if a device was upgraded to the specified driver.

Otherwise, it returns FALSE and the logged error can be retrieved with a call to GetLastError. Possible error values returned by GetLastError are included in the following table.

Comments

UpdateDriverForPlugAndPlayDevices scans the devices on the system and attempts to install the drivers specified by FullInfPath for any devices that match the specified HardwareId value.

The default behavior is to only install the specified drivers if they are better match than the currently installed drivers and the specified drivers are also a better match than any drivers in %SystemRoot%\inf. For more information, see How Setup Selects Drivers.

UpdateDriverForPlugAndPlayDevices can also be used to determine whether the device with the specified HardwareId value is plugged in. For more information, see Writing a Device Installation Application.

UpdateDriverForPlugAndPlayDevices sends an IRP_MN_QUERY_REMOVE_DEVICE request to the specified device, all the children of the device, and all other devices that are recursively part of the removal relations for the device. If any of these devices fail a query remove request, UpdateDriverForPlugAndPlayDevices sets the DI_NEEDREBOOT flag in the Flags member of the SP_DEVINSTALL_PARAMS structure for the device. For information about removal relations, see the IRP_MN_QUERY_DEVICE_RELATIONS request.

Generally, setup applications should supply NULL for bRebootRequired. So, the system will initiate a restart if necessary. An application should specify a pointer value only in the following cases:

• The application must call UpdateDriverForPlugAndPlayDevices several times to complete an installation.
• The application must perform other operations before the restart (if required) occurs.
• The application is a class installer, which should set DI_NEEDREBOOT in SP_DEVINSTALL_PARAMS if a restart is needed.

If the application must call UpdateDriverForPlugAndPlayDevices several times, it should save any TRUE restart status value received and then prompt for a restart after the final call has returned.

If the function returns ERROR_IN_WOW64 in a 32-bit application, the application is executing on a 64-bit system, which is not allowed. For more information, see Installing Devices on 64-Bit Systems.

Requirements

Versions: The UpdateDriverForPlugAndPlayDevices function is available in Microsoft Windows 2000 and later versions of Windows.

Headers: Declared in Newdev.h. Include Newdev.h.

Library: Contained in Newdev.lib. Link to Newdev.lib.