SetupDiBuildDriverInfoList

The SetupDiBuildDriverInfoList function builds a list of drivers associated with a specified device instance or with the device information set's global class driver list.

WINSETUPAPI BOOL WINAPI
  SetupDiBuildDriverInfoList(
    IN HDEVINFO DeviceInfoSet,
    IN OUT PSP_DEVINFO_DATA  DeviceInfoData,  OPTIONAL
    IN DWORD  DriverType
    );

Parameters

DeviceInfoSet

Supplies a handle to the device information set to contain the driver information list (either globally for all elements or specifically for a single element). The device information set must not contain remote elements.

DeviceInfoData

Supplies a pointer to the SP_DEVINFO_DATA structure for the device information element for which to build a driver list. If this parameter is NULL, the list is associated with the device information set and not with a particular device information element. Use NULL with driver lists of type SPDIT_CLASSDRIVER only.

If the class of this device is updated as a result of building a compatible driver list, the ClassGuid field of the SP_DEVINFO_DATA structure is updated upon return.

DriverType

Specifies what type of driver list to build. Must be one of the following values:

SPDIT_CLASSDRIVER

Build a list of class drivers.

SPDIT_COMPATDRIVER

Build a list of drivers for this device. DeviceInfoData must be specified if this flag is set.

Return Value

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

Headers

Declared in setupapi.h. Include setupapi.h.

Comments

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 to a directory containing INF files or a path to a specific INF file. If DI_ENUMSINGLEINF is set, DriverPath contains a path to a single INF file. If DriverPath is NULL, this function builds the driver list from the default INF file location, %windir%\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 machine. This function only searches for local drivers.

See Also

SetupDiCancelDriverInfoSearch, SetupDiDestroyDriverInfoList, SetupDiEnumDriverInfo