Using Device Installation Functions

This section summarizes the device installation functions. By using the device installation functions, the installation software can perform the following types of operations:

  • Install drivers

  • Handle DIF codes.

  • Manage device information sets.

  • Manage driver lists.

  • Manage device interfaces.

  • Manage icons and other bitmaps.

The following tables provide summaries of the following types of functions:

Driver Installation Functions

Device Information Functions

Driver Information Functions

Device Installation Handlers

Device Installation Customization Functions

Setup Class Functions

Bitmap and Icon Functions

Device Interface Functions

Device Property Functions (Windows Vista and Later)

Registry Functions

Other Functions

Driver Installation Functions

DiInstallDevice

Installs a specified driver package that is preinstalled in the driver store on a PnP device that is present in the system. (Windows Vista and later versions of Windows)

DiUninstallDevice

Uninstalls a device and removes its device node (devnode) from the system. (Windows 7 and later versions of Windows)

DiInstallDriver

Preinstalls a driver package in the driver store and then installs the driver package on matching PnP devices that are present in the system. (Windows Vista and later versions of Windows)

DiUninstallDriver

Removes a driver package from the Driver Store. (Windows 10 Version 1703 and later versions of Windows)

UpdateDriverForPlugAndPlayDevices

Updates the driver package that is installed for matching PnP devices that are present in the system.

DiRollbackDriver

Rolls back the driver package that is installed on a specified device to the backup driver package set for the device. (Windows Vista and later versions of Windows)

Device Information Functions

Note

SetupApi is not supported on all editions of Windows. When possible, you should use lower layer APIs such as those available via CfgMgr32.dll. See Porting from SetupApi to CfgMgr32 for tips.

SetupDiCreateDeviceInfoList

Creates an empty device information set. This set can be associated with a class GUID.

SetupDiCreateDeviceInfoListEx

Creates an empty device information set. This set can be associated with a class GUID and can be for devices on a remote computer.

SetupDiCreateDeviceInfo

Creates a new device information element and adds it as a new member to the specified device information set.

SetupDiOpenDeviceInfo

Retrieves information about an existing device instance and adds it to the specified device information set.

SetupDiEnumDeviceInfo

Returns a context structure for a device information element of a device information set.

SetupDiGetDeviceInstanceId

Retrieves the device instance ID associated with a device information element.

SetupDiGetDeviceInfoListClass

Retrieves the class GUID associated with a device information set if it has an associated class.

SetupDiGetDeviceInfoListDetail

Retrieves information associated with a device information set including the class GUID, remote computer handle, and remote computer name.

SetupDiGetClassDevPropertySheets

Retrieves handles to the property sheets of a specified device information element or of the device setup class of a specified device information set.

SetupDiGetClassDevs

Returns a device information set that contains all devices of a specified class.

SetupDiGetClassDevsEx

Returns a device information set that contains all devices of a specified class on a local or remote computer.

SetupDiSetSelectedDevice

Sets the specified device information element to be the currently-selected member of a device information set. This function is typically used by an installation wizard.

SetupDiGetSelectedDevice

Retrieves the currently-selected device for the specified device information set.

SetupDiRegisterDeviceInfo

Registers a newly created device instance with the Plug and Play manager.

SetupDiDeleteDeviceInfo

Deletes a member from the specified device information set. This function does not delete the actual device.

SetupDiDestroyDeviceInfoList

Destroys a device information set and frees all associated memory.

Driver Information Functions

SetupDiBuildDriverInfoList

Builds a list of drivers associated with a specified device instance or with the device information set's global class driver list.

SetupDiEnumDriverInfo

Enumerates the members of a driver information list.

SetupDiGetDriverInfoDetail

Retrieves detailed information for a specified driver information element.

SetupDiSetSelectedDriver

Sets the specified member of a driver list as the currently selected-driver. It can also be used to reset the driver list so that there is no currently-selected driver.

SetupDiGetSelectedDriver

Retrieves the member of a driver list that was selected as the driver to install.

SetupDiCancelDriverInfoSearch

Cancels a driver list search that is currently underway in a different thread.

SetupDiDestroyDriverInfoList

Destroys a driver information list.

Device Installation Handlers

SetupDiCallClassInstaller

Calls the appropriate class installer, and any registered co-installers, with the specified installation request.

SetupDiChangeState

The default handler for the DIF_PROPERTYCHANGE request. It can be used to change the state of an installed device.

SetupDiRegisterCoDeviceInstallers

Registers the device-specific co-installers listed in the INF file for the specified device. This function is the default handler for DIF_REGISTER_COINSTALLERS.

SetupDiInstallDevice

The default handler for the DIF_INSTALLDEVICE request.

SetupDiInstallDriverFiles

The default handler for the DIF_INSTALLDEVICEFILES request.

SetupDiInstallDeviceInterfaces

The default handler for the DIF_INSTALLINTERFACES request. It installs the interfaces that are listed in a DDInstall.Interfaces section of a device INF file.

SetupDiMoveDuplicateDevice

This function is obsolete and cannot be used in any version of Microsoft Windows.

SetupDiRemoveDevice

The default handler for the DIF_REMOVEDEVICE request.

SetupDiUnremoveDevice

The default handler for the DIF_UNREMOVE request.

SetupDiRegisterDeviceInfo

The default handler for the DIF_REGISTERDEVICE request.

SetupDiSelectDevice

The default handler for the DIF_SELECTDEVICE request.

SetupDiSelectBestCompatDrv

The default handler for the DIF_SELECTBESTCOMPATDRV request.

SetupDiSelectDevice

Default handler for the DIF_SELECTDEVICE request.

Device Installation Customization Functions

SetupDiGetClassInstallParams

Retrieves class install parameters for a device information set or a particular device information element.

SetupDiSetClassInstallParams

Sets or clears class install parameters for a device information set or a particular device information element.

SetupDiGetDeviceInstallParams

Retrieves device install parameters for a device information set or a particular device information element.

SetupDiSetDeviceInstallParams

Sets device install parameters for a device information set or a particular device information element.

SetupDiGetDriverInstallParams

Retrieves install parameters for the specified driver.

SetupDiSetDriverInstallParams

Sets the installation parameters for the specified driver.

Setup Class Functions

SetupDiBuildClassInfoList

Returns a list of setup class GUIDs that includes every class installed on the system.

SetupDiBuildClassInfoListEx

Returns a list of setup class GUIDs that includes every class installed on the local system or a remote system.

SetupDiGetClassDescription

Retrieves the class description associated with the specified setup class GUID.

SetupDiGetClassDescriptionEx

Retrieves the description of a setup class installed on a local or remote computer.

SetupDiGetINFClass

Retrieves the class of a specified device INF file.

SetupDiClassGuidsFromName

Retrieves the GUIDs associated with the specified class name. This list is built based on what classes are currently installed on the system.

SetupDiClassGuidsFromNameEx

Retrieves the GUIDs associated with the specified class name. This resulting list contains the classes currently installed on a local or remote computer.

SetupDiClassNameFromGuid

Retrieves the class name associated with the class GUID.

SetupDiClassNameFromGuidEx

Retrieves the class name associated with a class GUID. The class can be installed on a local or remote computer.

SetupDiInstallClass

Installs the ClassInstall32 section of the specified INF file.

SetupDiInstallClassEx

Installs a class installer or an interface class.

SetupDiOpenClassRegKey

Opens the device setup class registry key, or a specific subkey of the class.

SetupDiOpenClassRegKeyEx

Opens the device setup class registry key, the device interface class registry key, or a specific subkey of the class. This function opens the specified key on the local computer or on a remote computer.

Bitmap and Icon Functions

SetupDiGetClassImageList

Builds an image list that contains bitmaps for every installed class and returns the list in a data structure.

SetupDiGetClassImageListEx

Builds an image list of bitmaps for every class installed on a local or remote computer.

SetupDiGetClassImageIndex

Retrieves the index within the class image list of a specified class.

SetupDiGetClassBitmapIndex

Retrieves the index of the mini-icon supplied for the specified class.

SetupDiDrawMiniIcon

Draws the specified mini-icon at the location requested.

SetupDiLoadClassIcon

Loads both the large and mini-icon for the specified class.

SetupDiLoadDeviceIcon

Loads a device icon for a specified device. (Windows Vista and later versions of Windows)

SetupDiDestroyClassImageList

Destroys a class image list.

Device Interface Functions

Note

SetupApi is not supported on all editions of Windows. When possible, you should use lower layer APIs such as those available via CfgMgr32.dll. See Porting from SetupApi to CfgMgr32 for tips.

SetupDiCreateDeviceInterface

Registers device functionality (a device interface) for a device.

SetupDiOpenDeviceInterface

Retrieves information about an existing device interface and adds it to the specified device information set.

SetupDiGetDeviceInterfaceAlias

Returns an alias of the specified device interface.

SetupDiGetClassDevs

Returns a device information set that contains all devices of a specified class.

SetupDiGetClassDevsEx

Returns a device information set that contains all devices of a specified class on a local or remote computer.

SetupDiEnumDeviceInterfaces

Returns a context structure for a device interface element of a device information set. Each call returns information about one device interface.

The function can be called repeatedly to obtain information about several interfaces exposed by one or more devices.

SetupDiGetDeviceInterfaceDetail

Returns details about a particular device interface.

SetupDiCreateDeviceInterfaceRegKey

Creates a registry subkey for storing information about a device interface instance and returns a handle to the key.

SetupDiOpenDeviceInterfaceRegKey

Opens the registry subkey that is used by applications and drivers to store information that is specific to a device interface instance and returns a handle to the key.

SetupDiDeleteDeviceInterfaceRegKey

Deletes the registry subkey that was used by applications and drivers to store information that is specific to a device interface instance.

SetupDiInstallDeviceInterfaces

Is the default handler for the DIF_INSTALLINTERFACES request. It installs the interfaces that are listed in a DDInstall.Interfaces section of a device INF file.

SetupDiRemoveDeviceInterface

Removes a registered device interface from the system.

SetupDiDeleteDeviceInterfaceData

Deletes a device interface from a device information set.

SetupDiSetDeviceInterfaceDefault

Sets a specified device interface as the default interface for a device class.

SetupDiInstallClassEx

Installs a class installer or an interface class.

SetupDiOpenClassRegKeyEx

Opens the device setup class registry key, the device interface class registry key, or a specific subkey of the class. This function opens the specified key on the local computer or on a remote computer.

Device Property Functions (Windows Vista and Later)

Note

SetupApi is not supported on all editions of Windows. When possible, you should use lower layer APIs such as those available via CfgMgr32.dll. See Porting from SetupApi to CfgMgr32 for tips.

SetupDiGetClassProperty

Retrieves a device property that is set for a device setup class or a device interface class.

SetupDiGetClassPropertyEx

Retrieves a class property for a device setup class or a device interface class on a local or remote computer.

SetupDiGetClassPropertyKeys

Retrieves an array of the device property keys that represent the device properties that are set for a device setup class or a device interface class.

SetupDiGetClassPropertyKeysEx

Retrieves an array of the device property keys that represent the device properties that are set for a device setup class or a device interface class on a local or a remote computer.

SetupDiGetDeviceInterfaceProperty

Retrieves a device property that is set for a device interface.

SetupDiGetDeviceInterfacePropertyKeys

Retrieves an array of device property keys that represent the device properties that are set for a device interface.

SetupDiGetDeviceProperty

Retrieves a device instance property.

SetupDiGetDevicePropertyKeys

Retrieves an array of the device property keys that represent the device properties that are set for a device instance.

SetupDiSetClassProperty

Sets a class property for a device setup class or a device interface class.

SetupDiSetClassPropertyEx

Sets a device property for a device setup class or a device interface class on a local or remote computer.

SetupDiSetDeviceInterfaceProperty

Sets a device property of a device interface.

SetupDiSetDeviceProperty

Sets a device instance property.

Registry Functions

Note

SetupApi is not supported on all editions of Windows. When possible, you should use lower layer APIs such as those available via CfgMgr32.dll. See Porting from SetupApi to CfgMgr32 for tips.

SetupDiCreateDevRegKey

Creates a registry storage key for device-specific configuration information and returns a handle to the key.

SetupDiOpenDevRegKey

Opens a registry storage key for device-specific configuration information and returns a handle to the key.

SetupDiDeleteDevRegKey

Deletes the specified user-accessible registry key(s) associated with a device information element.

SetupDiOpenClassRegKey

Opens the setup class registry key, or a specific subkey of the class.

SetupDiOpenClassRegKeyEx

Opens the device setup class registry key, the device interface class registry key, or a specific subkey of the class.

This function opens the specified key on the local computer or on a remote computer.

SetupDiCreateDeviceInterfaceRegKey

Creates a nonvolatile registry subkey for storing information about a device interface instance and returns a handle to the key.

SetupDiOpenDeviceInterfaceRegKey

Opens the registry subkey that is used by applications and drivers to store information that is specific to a device interface instance and returns a handle to the key.

SetupDiDeleteDeviceInterfaceRegKey

Deletes the registry subkey that was used by applications and drivers to store information that is specific to a device interface instance.

SetupDiSetDeviceRegistryProperty

Sets the specified Plug and Play device property.

SetupDiGetDeviceRegistryProperty

Retrieves the specified Plug and Play device property.

SetupDiGetClassRegistryProperty

Retrieves a specified device class property from the registry.

SetupDiSetClassRegistryProperty

Sets a specified device class property in the registry.

Other Functions

SetupDiGetActualModelsSection

Retrieves the appropriate decorated INF Models section to use when installing a device from a device INF file.

SetupDiGetActualSectionToInstall

Retrieves the appropriate DDInstall section to use when installing a device from a device INF file.

SetupDiGetActualSectionToInstallEx

Retrieves the name of the INF DDInstall section that installs a device for a specified operating system and processor architecture.

SetupDiGetHwProfileFriendlyName

Retrieves the friendly name associated with a hardware profile ID.

SetupDiGetHwProfileFriendlyNameEx

Retrieves the friendly name associated with a hardware profile ID on a local or remote computer.

SetupDiGetHwProfileList

Retrieves a list of all currently defined hardware profile IDs.

SetupDiGetHwProfileListEx

Retrieves a list of all currently defined hardware profile IDs on a local or remote computer.

SetupDiRestartDevices

Restarts a specified device or, if necessary, starts all devices that are operated by the same function and filter drivers as the specified device.