DIF_SELECTBESTCOMPATDRV

A DIF_SELECTBESTCOMPATDRV request allows an installer to select the best driver from the device information element's compatible driver list.

When Sent

When the operating system is preparing to install a new PnP device or is performing a change-driver operation on a PnP device.

This DIF request is typically used during a PnP configuration. If a device is being manually installed, Windows sends a DIF_SELECTDEVICE request.

Who Handles

Installer Input

DeviceInfoSet
Supplies a handle to the device information set that contains the device.

DeviceInfoData
Supplies a pointer to an SP_DEVINFO_DATA structure that identifies the device in the device information set.

Device Installation Parameters
There are device installation parameters (SP_DEVINSTALL_PARAMS) associated with the DeviceInfoData.

Class Installation Parameters
None

Installer Output

Device Installation Parameters
An installer can modify the device installation parameters. However, they typically do not when handling this DIF request.

DeviceInfoData
As a side effect, an installer can modify the driver list associated with the DeviceInfoData, in particular, the SP_DRVINSTALL_PARAMS.

Installer Return Value

A co-installer can return NO_ERROR, ERROR_DI_POSTPROCESSING_REQUIRED, or a Win32 error code.

If a class installer successfully handles this request and SetupDiCallClassInstaller should subsequently call the default handler, the class installer returns ERROR_DI_DO_DEFAULT.

If the class installer successfully handles this request, including directly calling the default handler, the class installer should return NO_ERROR and SetupDiCallClassInstaller will not subsequently call the default handler again.

Note   The class installer can directly call the default handler, but the class installer should never attempt to supersede the operations of the default handler.

For more information about calling the default handler, see Calling Default DIF Code Handlers.

If the class installer encounters an error, the installer should return an appropriate Win32 error code and SetupDiCallClassInstaller will not subsequently call the default handler.

Default DIF Code Handler

SetupDiSelectBestCompatDrv

Installer Operation

An installer handles this DIF request to participate in selecting a driver for a PnP device. An installer typically responds to this DIF request in one of the following ways:

• Do nothing.

  If an installer has no special selection requirements, it does nothing in response to this DIF request. A class installer returns ERROR_DI_DO_DEFAULT and a co-installer returns NO_ERROR.

• Modify the parameters of one or more drivers in the driver list.

  For example, an installer might remove a driver from consideration for the device by marking it DNF_BAD_DRIVER. An installer modifies driver parameters by following these steps:

  1. Get the information about the first driver in the list by calling SetupDiEnumDriverInfo and SetupDiGetDriverInstallParams. If appropriate, modify the driver parameters and apply the change by calling SetupDiSetDriverInstallParams.

     If a driver is a worst-case choice, set the driver's rank to 0xFFFF or higher in the driver install parameters. See How Windows Selects Drivers for more information.

  2. Repeat the previous step until you have processed all the drivers in the list. Make sure that you increment the MemberIndex parameter to SetupDiEnumDriverInfo as described in the reference page for that function.

  After a class installer modifies the driver list, it returns ERROR_DI_DO_DEFAULT. If a co-installer modifies the driver list, it should do so in preprocessing and return NO_ERROR.

• Select the best driver for the device.

  This action is less common, but an installer might choose the best driver for the device. Such an installer would examine the data for each driver, choose a driver, and call SetupDiSetSelectedDriver to set the driver. After an installer sets the selected driver, it returns NO_ERROR.

  If a co-installer selects a driver, it should do so in postprocessing.

For more information about DIF codes, see Handling DIF Codes.

Requirements

See also

SetupDiSelectBestCompatDrv

SetupDiSetSelectedDriver

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS