2.4.2.6 Device Installation Functions Summary
Installers can use the device installation functions provided by Setup to carry out installation operations. The device installation functions allow installers to search INF files for compatible drivers, display driver choices to the user through selection dialogs, and perform the actual driver installation.
Most of the device installation functions rely on information in the SP_DEVINFO_DATA structure to carry out installation tasks. Each device has an SP_DEVINFO_DATA structure associated with it. You can retrieve a handle (HDEVINFO) to a device information set that contains all installed devices in a particular class by using the SetupDiGetClassDevs function. You can use the SetupDiCreateDeviceInfo function to add a new device to a device information set. You can free all SP_DEVINFO_DATA structures in a device information set by using the SetupDiDestroyDeviceInfoList function. This function also frees any compatible device and class device lists that may have been added to the structure.
By using the SetupDiBuildDriverInfoList function, you can generate a list of selections from which the installer or the user can choose the driver or device to install. SetupDiBuildDriverInfoList creates a list of compatible drivers or a list of all devices of a particular class.
Once you have a list of compatible drivers, you can prompt the user to select from the list by using the SetupDiSelectDevice function. This function displays a dialog box that contains information about each device in the device information set. You can install a selected driver by using the SetupDiInstallDevice function. This function uses information in the driver’s INF file to create to any new registry entries required, set the configuration of the device hardware, and copy the driver files to the appropriate directories.
An installer might need to examine and set values under the registry key for a device that is about to be installed. You can open the hardware or driver key for a device by using the SetupDiCreateDevRegKey or SetupDiOpenDevRegKey function.
You can install a new class of device by using the SetupDiInstallClass function. This function installs the new class of device from an INF file that contains a ClassInstall32 section.
You can remove a device from the system by using the SetupDiRemoveDevice function. This function deletes the device’s registry entries and stops the device if possible. If the device cannot be dynamically stopped, the function sets flags that eventually cause the user to be prompted to shut down the system.
Some device installation functions are intended to be used by the system and may not be useful for ordinary installers. You can call the installer for a particular class by using the SetupDiCallClassInstaller function. This function is useful if a device installer needs support from the corresponding class installer to complete installation. The function uses the class GUID in the HDEVINFO handle or SP_DEVINFO_DATA structure to locate, load, and call the appropriate class installer.
The device installation functions are briefly summarized below. See Device Installation Functions Reference for a detailed description of the these functions.
| SetupDiAskForOEMDisk | Displays a dialog that asks the user for the path to an OEM installation disk. |
| SetupDiBuildClassInfoList | Returns a list of class GUIDs that includes every class installed on the system. |
| SetupDiBuildDriverInfoList | Builds a list of drivers associated with a specified device instance or with the device information set's global class driver list. The drivers can be either class drivers or device drivers. |
| SetupDiCallClassInstaller | Calls the appropriate class installer with the specified installation request. |
| SetupDiCancelDriverInfoSearch | Cancels a driver list search that is currently underway in a different thread. |
| SetupDiChangeState | The default handler for the DIF_PROPERTYCHANGE class installation request. It can be used to change the state of an installed device. |
| SetupDiClassGuidsFromName | Retrieves the GUID(s) associated with the specified class name. This list is built based on what classes are currently installed on the system. |
| SetupDiClassNameFromGuid | Retrieves the class name associated with the class GUID. |
| SetupDiCreateDeviceInfo | Creates a new device information element and adds it as a new member to the specified device information set. |
| SetupDiCreateDeviceInfoList | Creates an empty device information set. This set can be associated with a class GUID. |
| SetupDiCreateDevRegKey | Creates a registry storage key for device-specific configuration information and returns a handle to the key. |
| SetupDiDeleteDeviceInfo | Deletes a member from the specified device information set. This function does not delete the actual device. |
| SetupDiDeleteDevRegKey | Deletes the specified registry key(s) associated with a device information element. |
| SetupDiDestroyClassImageList | Destroys a class image list. |
| SetupDiDestroyDeviceInfoList | Destroys a device information set and frees all associated memory. |
| SetupDiDestroyDriverInfoList | Destroys a driver information list. |
| SetupDiDrawMiniIcon | Draws the specified mini-icon at the location requested. |
| SetupDiEnumDeviceInfo | Enumerates the members of the specified device information set. |
| SetupDiEnumDriverInfo | Enumerates the members of a driver information list. |
| SetupDiGetActualSectionToInstall | Finds the appropriate Install section to use when installing a device from a Windows NT 4.0/Windows 95 INF file. |
| SetupDiGetClassBitmapIndex | Retrieves the index of the mini-icon supplied for the specified class. |
| SetupDiGetClassDescription | Retrieves the class description associated with the specified class GUID. |
| SetupDiGetClassDevs | Returns a device information set that contains all installed devices of a specified class. |
| SetupDiGetClassImageIndex | Retrieves the index within the class image list of a specified class. |
| SetupDiGetClassImageList | Builds an image list that contains bitmaps for every installed class and returns the list in a data structure. |
| SetupDiGetClassInstallParams | Retrieves class install parameters for a device information set or a particular device information element. |
| SetupDiGetDeviceInfoListClass | Retrieves the class GUID associated with a device information set if it has an associated class. |
| SetupDiGetDeviceInstallParams | Retrieves install parameters for a device information set or a particular device information element. |
| SetupDiGetDeviceInstanceId | Retrieves the device instance ID associated with a device information element. |
| SetupDiGetDeviceRegistryProperty | Retrieves the specified property from the Plug and Play device storage location in the registry. |
| SetupDiGetDriverInfoDetail | Retrieves detailed information for a specified driver. |
| SetupDiGetDriverInstallParams | Retrieves install parameters for the specified driver. |
| SetupDiGetHwProfileFriendlyName | Retrieves the friendly name associated with a hardware profile ID. |
| SetupDiGetHwProfileList | Retrieves a list of all currently defined hardware profile IDs. |
| SetupDiGetINFClass | Retrieves the class of a specified Windows NT 4.0-style INF file. |
| SetupDiGetSelectedDevice | Retrieves the currently-selected device for the specified device information set. |
| SetupDiGetSelectedDriver | Retrieves the member of a driver list that has been selected as the controlling driver. |
| SetupDiGetWizardPage | Retrieves a handle to one of the wizards provided by the Setup program for an application to include in its own wizard. |
| SetupDiInstallClass | Installs the ClassInstall32 section of the specified INF file. |
| SetupDiInstallDevice | The default handler for the DIF_INSTALLDEVICE class installation request. |
| SetupDiInstallDriverFiles | The default handler for the DIF_INSTALLDEVICEFILES class installation request. |
| SetupDiLoadClassIcon | Loads both the large and mini-icon for the specified class. |
| SetupDiMoveDuplicateDevice | The default handler for the DIF_MOVEDEVICE class installation request. |
| SetupDiOpenClassRegKey | Opens the class registry key or a specific class' subkey. |
| SetupDiOpenDeviceInfo | Retrieves information about an existing device instance and adds it to the specified device information set. |
| SetupDiOpenDevRegKey | Opens a registry storage key for device-specific configuration information and returns a handle to the key. |
| SetupDiRegisterDeviceInfo | Registers a device instance with the Plug and Play Manager. |
| SetupDiRemoveDevice | Removes a device from the system. |
| SetupDiSelectDevice | The default handler for the DIF_SELECTDEVICE class installation request. |
| SetupDiSelectOEMDrv | Selects a driver for a device using an OEM path supplied by the user. |
| SetupDiSetClassInstallParams | Sets or clears class install parameters for a device information set or a particular device information element. |
| SetupDiSetDeviceInstallParams | Sets install parameters for a device information set or a particular device information element. |
| SetupDiSetDeviceRegistryProperty | Sets the specified Plug and Play device registry property. |
| 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. |
| 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. |