SetupDiRemoveDevice function (setupapi.h)

Article
10/13/2021

The SetupDiRemoveDevice function is the default handler for the DIF_REMOVE installation request.

Syntax

WINSETUPAPI BOOL SetupDiRemoveDevice(
  [in]      HDEVINFO         DeviceInfoSet,
  [in, out] PSP_DEVINFO_DATA DeviceInfoData
);

Parameters

[in] DeviceInfoSet

A handle to a device information set for the local system that contains a device information element that represents the device to remove.

[in, out] DeviceInfoData

A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet. This is an IN-OUT parameter because DeviceInfoSet.DevInst might be updated with a new handle value upon return. If this is a global removal or the last hardware profile-specific removal, all traces of the device instance are deleted from the registry and the handle will be NULL.

Return value

The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be retrieved by a call to GetLastError.

Remarks

SetupDiRemoveDevice removes the device from the system. It deletes the device's hardware and software registry keys and any hardware-profile-specific registry keys (configuration-specific registry keys). This function dynamically stops the device if its DevInst is active and this is a global removal or the last configuration-specific removal. If the device cannot be dynamically stopped, flags are set in the Install Parameter block of the device information set that eventually cause the user to be prompted to restart the computer.

Device removal is either global to all hardware profiles or specific to one hardware profile as specified by the Scope member of the SP_REMOVEDEVICE_PARAMS structure that supplies the class installation parameters for the DIF_REMOVE request. Configuration-specific removal is only appropriate for root-enumerated devices and should only be requested by system code.

The caller of SetupDiRemoveDevice must be a member of the Administrators group.

Note Only a class installer should call SetupDiRemoveDevice and only in those situations where the class installer must perform device removal operations after SetupDiRemoveDevice completes the default device removal operation. In such situations, the class installer must directly call SetupDiRemoveDevice when the installer processes a DIF_REMOVE request. For more information about calling the default handler, see Calling Default DIF Code Handlers.

Requirements

Requirement	Value
Minimum supported client	Available in Microsoft Windows 2000 and later versions of Windows.
Target Platform	Desktop
Header	setupapi.h (include Setupapi.h)
Library	Setupapi.lib
DLL	Setupapi.dll