爱华网Given an INF file and a hardwareID, the UpdateDriverForPlugAndPlayDevicesfunction installs updated drivers for devices that match thehardware ID.
Syntax
C++BOOL UpdateDriverForPlugAndPlayDevices( _In_opt_HWND hwndParent, _In_LPCTSTR HardwareId, _In_LPCTSTR FullInfPath, _In_DWORD InstallFlags, _Out_opt_PBOOL bRebootRequired);
Parameters
- hwndParent [in, optional]
A handle to the top-level w indow to use for any UI related toinstalling devices.
- HardwareId [in]
A pointer to a NULL-terminated string that supplies the hardwareidentifier to match existing devices on the computer. The maximumlength of a NULL-terminated hardware identifier isMAX_DEVICE_ID_LEN. For more information about hardware identifiers,see DeviceIdentification Strings.
- FullInfPath [in]
A pointer to a NULL-terminated string that supplies the fullpath file name of an INF file. The files should be on thedistribution media or in a vendor-created directory, not in asystem location such as %SystemRoot%inf.UpdateDriverForPlugAndPlayDevices copies driverfiles to the appropriate system locations if the installation issuccessful.
- InstallFlags [in]
A caller-supplied value created by using OR to combine zero ormore of the following bit flags:
- INSTALLFLAG_FORCE
If this flag is set and the function finds a device that matchesthe HardwareId value, the function installs new driversfor the device whether better drivers already exist on thecomputer.
ImportantUsethis flag only with extreme caution. Setting this flag can cause anolder driver to be installed over a newer driver, if a user runsthe vendor's application after newer drivers are available.
- INSTALLFLAG_READONLY
If this flag is set, the function will not copy, rename, ordelete any installation files. Use of this flag should be limitedto 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 returnFALSE 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 Ifthis flag is set and a UI display is attempted, the device can beleft in an indeterminate state.
The InstallFlags parameter is typically zero.
- bRebootRequired [out, optional]
A pointer to a BOOL-typed variable that indicates whether arestart is required and who should prompt for it. This pointer isoptional and can be NULL.
If the pointer is NULL,UpdateDriverForPlugAndPlayDevices prompts for arestart after installing drivers, if necessary. If the pointer issupplied, the function returns a BOOLEAN value that isTRUE if the system should be restarted. It is thenthe caller's responsibility to prompt for a restart.
For more information, see the following Remarkssection.
Return value
The function returns TRUE if a device wasupgraded to the specified driver.
Otherwise, it returns FALSE and the loggederror can be retrieved with a call toGetLastError. Possible error values returned byGetLastError are included in the followingtable.
| Return code | Description |
|---|---|
| The path that was specified for FullInfPath does notexist. |
| The calling application is a 32-bit application attempting toexecute in a 64-bit environment, which is not allowed. |
| The value specified for InstallFlags is invalid. |
| The value specified for HardwareId does not match anydevice on the system. That is, the device is not plugged in. |
| The function found a match for the HardwareId value,but the specified driver was not a better match than the currentdriver and the caller did not specify the INSTALLFLAG_FORCEflag. |
Remarks
UpdateDriverForPlugAndPlayDevices scans thedevices on the system and attempts to install the drivers specifiedby FullInfPath for any devices that match the specifiedHardwareId value.
The default behavior is to only install the specified drivers ifthey are better match than the currently installed drivers and thespecified drivers are also a better match than any drivers in%SystemRoot%inf. For more information, seeHowWindows Selects Drivers.
UpdateDriverForPlugAndPlayDevices can also beused to determine whether the device with the specifiedHardwareId value is plugged in. For more information, seeWriting aDevice Installation Application.
UpdateDriverForPlugAndPlayDevices sends anIRP_MN_QUERY_REMOVE_DEVICE request to the specifieddevice, all the children of the device, and all other devices thatare recursively part of the removal relations for the device. Ifany of these devices fail a query remove request,UpdateDriverForPlugAndPlayDevices sets theDI_NEEDREBOOT flag in the Flags member of theSP_DEVINSTALL_PARAMS structure for the device. Forinformation about removal relations, see the IRP_MN_QUERY_DEVICE_RELATIONS request.
Generally, device installationapplications should supply NULL forbRebootRequired. So, the system will initiate a restart ifnecessary. An application should specify a pointer valueonly in the following cases:
If the application must callUpdateDriverForPlugAndPlayDevices several times,it should save any TRUE restart status valuereceived and then prompt for a restart after the final call hasreturned.
If the function returns ERROR_IN_WOW64 in a 32-bit application,the application is executing on a 64-bit system, which is notallowed. For more information, see InstallingDevices on 64-Bit Systems.
Requirements
Version | Available in Microsoft Windows 2000 and later versions ofWindows. |
|---|---|
Header |
|
Library |
|
