DiUninstallDevice function (newdev.h)
The DiUninstallDevice function uninstalls a device and removes its device node (devnode) from the system. This differs from using SetupDiCallClassInstaller with the DIF_REMOVE code because it attempts to uninstall the device node in addition to child devnodes that are present at the time of the call.
Prior to Windows 8 any child devices that are not present at the time of the call will not be uninstalled. However, beginning with Windows 8, any child devices that are not present at the time of the call will be uninstalled.
Syntax
BOOL DiUninstallDevice(
[in] HWND hwndParent,
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in] DWORD Flags,
[out, optional] PBOOL NeedReboot
);
Parameters
[in] hwndParent
A handle to the top-level window that is used to display any user interface component that is associated with the uninstallation request for the device. This parameter is optional and can be set to NULL.
[in] DeviceInfoSet
A handle to the device information set that contains a device information element. This element represents the device to be uninstalled through this call.
[in] DeviceInfoData
A pointer to an SP_DEVINFO_DATA structure that represents the specified device in the specified device information set for which the uninstallation request is performed.
[in] Flags
A value of type DWORD that specifies device uninstallation flags. Starting with Windows 7, this parameter must be set to zero.
[out, optional] NeedReboot
A pointer to a value of type BOOL that DiUninstallDevice sets to indicate whether a system restart is required to complete the device uninstallation request. This parameter is optional and can be set to NULL.
If the parameter is given and a system restart is required, DiUninstallDevice sets the value to TRUE. In this case, the application must prompt the user to restart the system. If this parameter is supplied and a system restart is not required, DiUninstallDevice sets the value to FALSE.
If this parameter is NULL and a system restart is required to complete the device uninstallation, DiUninstallDevice displays a system restart dialog box.
For more information about this parameter, see the Remarks section.
Return value
DiUninstallDevice returns TRUE if the function successfully uninstalled the top-level device node that represents the device. Otherwise, DiUninstallDevice returns FALSE, and the logged error can be retrieved by making a call to GetLastError. The following list shows some of the more common error values that GetLastError might return for this API:
| Return code | Description |
|---|---|
|
The caller does not have Administrator privileges. By default, Windows requires that the caller have Administrator privileges to uninstall devices. |
|
The value that is specified for the Flags parameter is not equal to zero. |
Remarks
DiUninstallDevice performs the same function as SetupDiCallClassInstaller when used with the DIF_REMOVE code. The key difference is that child devnodes for the top-level device are also deleted. DiUninstallDevice only returns failure if the top-level device node failed to be uninstalled, which is consistent with the behavior of SetupDiCallClassInstaller when used with the DIF_REMOVE code. Detailed information about whether child devnode uninstallation succeeded is available in the Setupapi.dev.log file.
The device to be uninstalled is specified by providing a device information set that includes the referenced device, and a SP_DEVINFO_DATA structure for the specific device. These are provided in the DeviceInfoSet and DeviceInfoData parameters.
To create a device information set that contains the specified device and to obtain an SP_DEVINFO_DATA structure for the device, complete one of the following tasks:
-
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.
- Call SetupDiEnumDeviceInfo 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.
However, if the application manages the notification of a required system restart, it must set the NeedReboot parameter to a non-NULL value. DiUninstallDevice sets the NeedReboot parameter to TRUE or FALSE, depending on whether a system restart is required.
The following list shows examples of why the application might manage the system restart:
- The application has to uninstall several devices. After all the devices are uninstalled, the application should prompt the user to restart the system if any call to DiUninstallDevice returned TRUE in the NeedReboot parameter.
- The application requires some other operations to occur before the system can be restarted. 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 this 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 7 and later versions of Windows. |
| Target Platform | Desktop |
| Header | newdev.h (include Newdev.h) |
| Library | Newdev.lib |
| DLL | Newdev.dll |