DiInstallDevice function (newdev.h)

Article
10/13/2021

The DiInstallDevice function installs a specified driver that is preinstalled in the driver store on a specified device that is present in the system.

Syntax

BOOL DiInstallDevice(
  [in, optional]  HWND             hwndParent,
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in, optional]  PSP_DRVINFO_DATA DriverInfoData,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

Parameters

[in, optional] hwndParent

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

[in] DeviceInfoSet

A handle to a device information set that contains a device information element that represents the specified device.

[in] DeviceInfoData

A pointer to an SP_DEVINFO_DATA structure that represents the specified device in the specified device information set.

[in, optional] DriverInfoData

An pointer to an SP_DRVINFO_DATA structure that specifies the driver to install on the specified device. This parameter is optional and can be set to NULL. If this parameter is NULL, DiInstallDevice searches the drivers preinstalled in the driver store for the driver that is the best match to the specified device, and, if one is found, installs the driver on the specified device.

[in] Flags

A value of type DWORD that specifies zero or the following flag:

DIIDFLAG_SHOWSEARCHUI

If the caller does not specify a driver (DriverInfoData is set to NULL) and DiInstallDevice does not locate a preinstalled driver that matches the specified device. Instead, DiInstallDevice displays the Found New Hardware wizard for the device.

DIIDFLAG_NOFINISHINSTALLUI

DiInstallDevice does not start finish-install wizard pages or finish-install actions. The caller of DiInstallDevice must start these operations. The caller should only specify this flag if the caller requires that finish-install wizard pages be invoked in the context of a caller-supplied user interface component.

DIIDFLAG_INSTALLNULLDRIVER

DiInstallDevice attempts to install a null driver on the specified device. If this flag is set, DiInstallDevice does not use the DriverInfoData parameter. DiInstallDevice removes all device settings and, if the device cannot run in raw mode, the function sets the status of the device to CM_PROB_FAILED_INSTALL. If DiInstallDevice cannot install a null driver, the resulting state of the device is the same as if the device was connected for the first time to the computer and Windows did not locate a driver for the device.

DIIDFLAG_INSTALLCOPYINFDRIVERS

Any additional INF file specified via a CopyINF directive will be installed on any device it is applicable to. Any failure in installing an additional INF will not cause the primary INF's installation to fail.

[out, optional] NeedReboot

A pointer to a value of type BOOL that DiInstallDevice sets to indicate whether a system restart is required to complete the installation. This parameter is optional and can be set to NULL. If this parameter is supplied and a system restart is required to complete the installation, DiInstallDevice sets the value to TRUE. In this case, the caller is responsible for restarting the system. If this parameter is supplied and a system restart is not required, DiInstallDevice sets this parameter to FALSE. If this parameter is NULL and a system restart is required to complete the installation, DiInstallDevice displays a system restart dialog box.

Return value

DiInstallDevice returns TRUE if the function successfully installed the specified driver on the specified device. Otherwise, DiInstallDevice returns FALSE and the logged error can be retrieved by making a call to GetLastError. Some of the more common error values that GetLastError might return are as follows:

Return code	Description
ERROR_ACCESS_DENIED	The caller does not have Administrator privileges. By default, Windows Vista and Windows Server 2008 require that a calling process have Administrator privileges to install a driver on a device.
ERROR_INVALID_FLAGS	The value that is specified for Flags is not zero or a bitwise OR of the valid flags.
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

Only call DiInstallDevice if it is necessary to install a specific driver on a specific device. Otherwise, use UpdateDriverForPlugAndPlayDevices or DiInstallDriver to install a driver for a device. For more information about which of these functions to call to install a driver on a device, see SetupAPI Functions that Simplify Driver Installation.

Before calling DiInstallDevice, the caller must obtain an SP_DEVINFO_DATA structure to specify the device and, optionally, an SP_DRVINFO_DATA structure to specify a driver for the device.

To create a device information set that contains the specified device and to obtain an SP_DEVINFO_DATA structure for the device, do one of the following:

Call SetupDiGetClassDevs to retrieve a device information set that contains the device and then call SetupDiEnumDeviceInfo to enumerate the devices in the device information set. On each call, SetupDiEnumDeviceInfo returns an SP_DEVINFO_DATA structure that represents the enumerated device in the device information set. To obtain specific information about the enumerated device, call SetupDiGetDeviceProperty and supply the SP_DEVINFO_DATA structure that is returned by SetupDiEnumDeviceInfo.
- OR -
Call SetupDiOpenDeviceInfo to add a device with a known device instance ID to the device information set. SetupDiOpenDeviceInfo returns an SP_DEVINFO_DATA structure that represents the device in the device information set.

To retrieve an SP_DRVINFO_DATA structure for a selected driver, call SetupDiBuildDriverInfoList to build a list of drivers for the device and then call SetupDiEnumDriverInfo to enumerate the elements of the driver list for the device. For each enumerated driver, SetupDiEnumDriverInfo retrieves an SP_DRVINFO_DATA structure that identifies the driver. SetupDiGetDriverInfoDetail can also be called to retrieve additional detail about an enumerated driver.

In general, an installation application should set NeedReboot to NULL. This ensures that DiInstallDevice prompts 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 DiInstallDevice 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 DiInstallDevice and, if so, prompt the user to restart the system after the final call to DiInstallDevice returns.
The application must perform required operations, other than calling DiInstallDevice, 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.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of Windows.
Target Platform	Desktop
Header	newdev.h (include Newdev.h)
Library	Newdev.lib
DLL	Newdev.dll

Share via