Export (0) Print
Expand All
Expand Minimize

DiInstallDriver function

The DiInstallDriver function preinstalls a driver in the driver store and then installs the driver on devices present in the system that the driver supports.

Syntax


BOOL DiInstallDriver(
  _In_opt_  HWND    hwndParent,
  _In_      LPCTSTR FullInfPath,
  _In_      DWORD   Flags,
  _Out_opt_ PBOOL   NeedReboot
);

Parameters

hwndParent [in, optional]

A handle to the top-level window that DiInstallDriver uses to display any user interface component that is associated with installing the device. This parameter is optional and can be set to NULL.

FullInfPath [in]

A pointer to a NULL-terminated string that supplies the fully qualified path of the INF file for the driver package.

Flags [in]

A value of type DWORD that specifies zero or DIIRFLAG_FORCE_INF. Typically, this flag should be set to zero.

If this flag is zero, DiInstallDriver only installs the specified driver on a device if the driver is a better match for a device than the driver that is currently installed on a device. However, if this flag is set to DIIRFLAG_FORCE_INF, DiInstallDriver installs the specified driver on a matching device whether the driver is a better match for the device than the driver that is currently installed on the device.

Caution  Forcing the installation of the driver can result in replacing a more compatible or newer driver with a less compatible or older driver.

For information about how Windows selects a driver for a device, see How Windows Selects Drivers.

NeedReboot [out, optional]

A pointer to a value of type BOOL that DiInstallDriver sets to indicate whether a system is restart is required to complete the installation. This parameter is optional and can be NULL. If the parameter is supplied and a system restart is required to complete the installation, DiInstallDriver sets the value to TRUE. In this case, the caller must prompt the user to restart the system. If this parameter is supplied and a system restart is not required to complete the installation, DiInstallDriver sets the value to FALSE. If the parameter is NULL and a system restart is required to complete the installation, DiInstallDriver displays a system restart dialog box. For more information about this parameter, see the following Remarks section.

Return value

DiInstallDriver returns TRUE if the function successfully preinstalled the specified driver package in the driver store. DiInstallDriver also returns TRUE if the function successfully installed the driver on one or more devices in the system. If the driver package is not successfully installed in the driver store, DiInstallDriver returns FALSE and the logged error can be retrieved by making call to GetLastError. Some of the more common error values that GetLastError might return are as follows:

Return codeDescription
ERROR_ACCESS_DENIED

The caller does not have Administrator privileges. By default, Windows requires that the caller have Administrator privileges to preinstall a driver package in the driver store.

ERROR_FILE_NOT_FOUND

The path of the specified INF file does not exist.

ERROR_INVALID_FLAGS

The value specified for Flags is not equal to zero or DIIRFLAG_FORCE_INF.

ERROR_IN_WOW64

The calling application is a 32-bit application that is attempting to execute in a 64-bit environment, which is not allowed. For more information, see Installing Devices on 64-Bit Systems.

 

Remarks

DiInstallDriver performs the following operations:

  1. Preinstalls the driver package in the driver store. If there is an instance of the same driver package already preinstalled in the driver store, DiInstallDriver first removes that instance and then adds the new instance of the driver package to the driver store.

  2. Enumerates devices that are present in the system.

  3. If Flags is equal to zero, installs the driver on a device only if the specified driver is a better match for the device than the driver that is currently installed on the device.

  4. If Flags is equal to DIIRFLAG_FORCE_INF, installs the driver on a device regardless of whether the driver package is the better match to the device than the driver that is currently installed on the device.

In general, an installation application should set NeedReboot to NULL to direct DiInstallDriver to prompt the user to restart the system if a restart is required to complete the installation. An application should supply a NeedReboot pointer only in the following cases:

  • The application must call DiInstallDriver several times to complete an installation. In this case, the application should record whether a TRUENeedReboot value is returned by any of the calls to DiInstallDriver and, if so, prompt the user to restart the system after the final call to DiInstallDriver returns.

  • The application must perform required operations, other than calling DiInstallDriver, before a system restart should occur. If a system restart is required, the application should finish the required operations and then prompt the user to restart the system.

  • The application is a class installer, in which case, the class installer should set the DI_NEEDREBOOT flag in the Flags member of the SP_DEVINSTALL_PARAMS structure for a device.

To install a selected driver on a selected device, call DiInstallDevice or InstallSelectedDriver. For more information about which of these functions to call to install a selected driver on a selected device, see SetupAPI Functions that Simplify Driver Installation.

Requirements

Target platform

Desktop

Version

Available in Windows Vista and later versions of Windows.

Header

Newdev.h (include Newdev.h)

Library

Newdev.lib

See also

DiInstallDevice
InstallSelectedDriver

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft