SetupDiBuildDriverInfoList function (setupapi.h)
The SetupDiBuildDriverInfoList function builds a list of drivers that is associated with a specific device or with the global class driver list for a device information set.
Syntax
WINSETUPAPI BOOL SetupDiBuildDriverInfoList(
[in] HDEVINFO DeviceInfoSet,
[in, out] PSP_DEVINFO_DATA DeviceInfoData,
[in] DWORD DriverType
);
Parameters
[in] DeviceInfoSet
A handle to the device information set to contain the driver list, either globally for all device information elements or specifically for a single device information element. The device information set must not contain remote device information elements.
[in, out] DeviceInfoData
A pointer to an SP_DEVINFO_DATA structure for the device information element in DeviceInfoSet that represents the device for which to build a driver list. This parameter is optional and can be NULL. If this parameter is specified, the list is associated with the specified device. If this parameter is NULL, the list is associated with the global class driver list for DeviceInfoSet.
If the class of this device is updated because of building a compatible driver list, DeviceInfoData.ClassGuid is updated upon return.
[in] DriverType
The type of driver list to build. Must be one of the following values:
Return value
The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be retrieved by making a call to GetLastError.
Remarks
The device information set should be for a local computer because SetupDiBuildDriverInfoList searches for drivers only on a local computer. If the device information set is for a remote computer, the function returns TRUE but does not actually update the existing driver list for the device information set or, if supplied, the driver list for the device information element.
The caller can set Flags in the SP_DEVINSTALL_PARAMS that are associated with the device information set or with a specific device (DeviceInfoData) to control how the list is built. For example, the caller can set the DI_FLAGSEX_ALLOWEXCLUDEDDRVS flag to include drivers that are marked Exclude From Select.
A driver is "Exclude From Select" if either it is marked ExcludeFromSelect in the INF file or it is a driver for a device whose whole setup class is marked NoInstallClass or NoUseClass in the class installer INF file. Drivers for PnP devices are typically "Exclude From Select"; PnP devices should not be manually installed. To build a list of driver files for a PnP device a caller of SetupDiBuildDriverInfoList must set this flag.
The DriverPath in the SP_DEVINSTALL_PARAMS contains either a path of a directory that contain INF files or a path of a specific INF file. If DI_ENUMSINGLEINF is set, DriverPath contains a path of a single INF file. If DriverPath is NULL, this function builds the driver list from the default INF file location, %SystemRoot%\inf.
After this function has built the specified driver list, the caller can enumerate the elements of the list by calling SetupDiEnumDriverInfo.
If the driver list is associated with a device instance (that is, DeviceInfoData is specified), the resulting list is composed of drivers that have the same class as the device instance with which they are associated. If this is a global class driver list (that is, DriverType is SPDIT_CLASSDRIVER and DeviceInfoData is not specified), the class that is used when building the list is the class associated with the device information set. If the device information set has no associated class, drivers of all classes are used when building the list.
Another thread can terminate the building of a driver list by a call to SetupDiCancelDriverInfoSearch.
The DeviceInfoSet must only contain elements on the local computer. This function only searches for local drivers.
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 |
| API set | ext-ms-win-setupapi-classinstallers-l1-1-1 (introduced in Windows 8.1) |