DIF_SELECTDEVICE

Article
06/15/2023

Une demande de DIF_SELECTDEVICE permet à un programme d’installation de participer à la sélection du pilote d’un appareil.

Date d’envoi

Lors du choix d’un pilote pour un appareil nouvellement énuméré ou d’un nouveau pilote pour un appareil existant (changer de pilote). Par exemple, lorsqu’un utilisateur sélectionne Ajouter/Supprimer du matériel et sélectionne la classe de modem. Ou bien, un utilisateur insère un appareil PnP et sélectionne « Choisir un pilote dans une liste » dans l’Assistant Nouveau matériel trouvé.

Qui gère

Co-programme d’installation de classe	Peut gérer
Co-programme d’installation d’appareil	Ne gère pas
Programme d’installation de classe	Peut gérer

Entrée du programme d’installation

DeviceInfoSet
Fournit un handle au jeu d’informations sur l’appareil qui contient l’appareil pour lequel un pilote doit être sélectionné. Une classe de configuration d’appareil est associée à DeviceInfoSet.

DeviceInfoData
Fournit éventuellement un pointeur vers une structure SP_DEVINFO_DATA qui identifie l’appareil dans le jeu d’informations de l’appareil.

Si DeviceInfoData a la valeur NULL, cette demande consiste à sélectionner un pilote pour la classe d’installation de l’appareil associée à DeviceInfoSet.

Paramètres d’installation de l’appareil
Si DeviceInfoData n’a pas la valeur NULL, des paramètres d’installation d’appareil (SP_DEVINSTALL_PARAMS) sont associés à DeviceInfoData. Si DeviceInfoData a la valeur NULL, des paramètres d’installation d’appareil sont associés à DeviceInfoSet.

Le DriverPath présente un intérêt particulier, qui contient l’emplacement du ou des INF à utiliser lors de la création de la liste des pilotes.

Paramètres d’installation de classe
Une structure SP_SELECTDEVICE_PARAMS est associée à DeviceInfoData si DeviceInfoData n’a pas la valeur NULL. Sinon, les paramètres d’installation de classe sont associés à l’ensemble des informations de l’appareil.

Sortie du programme d’installation

Paramètres d’installation de l’appareil
Un programme d’installation peut modifier les paramètres d’installation de l’appareil. Toutefois, il ne doit pas modifier le champ DriverPath .

Paramètres d’installation de classe
Un programme d’installation peut modifier le SP_SELECTDEVICE_PARAMS. Par exemple, un programme d’installation peut spécifier un titre et/ou des instructions que Windows doit utiliser dans la boîte de dialogue qui demande à l’utilisateur de sélectionner un pilote.

Si un programme d’installation définit de nouveaux paramètres select-device, par opposition à la modification des paramètres définis par un programme d’installation précédent, le programme d’installation doit zéro les champs qu’il ne définit pas.

Valeur de retour du programme d’installation

Si un co-programme d’installation ne fait rien pour ce code DIF, il retourne NO_ERROR de sa passe de prétraitement. Si un co-programme d’installation gère ce code DIF, il doit le faire dans son passage de prétraitement et retourner NO_ERROR ou un code d’erreur Win32. Au moment où un co-programme d’installation est appelé pour le post-traitement, le pilote a déjà été sélectionné.

Si un programme d’installation de classe gère correctement cette demande et que SetupDiCallClassInstaller doit ensuite appeler le gestionnaire par défaut, le programme d’installation de classe retourne ERROR_DI_DO_DEFAULT.

Si le programme d’installation de classe gère correctement cette demande, notamment en appelant directement le gestionnaire par défaut, le programme d’installation de classe doit retourner NO_ERROR et SetupDiCallClassInstaller n’appellera plus le gestionnaire par défaut par la suite.

Note Le programme d’installation de classe peut appeler directement le gestionnaire par défaut, mais le programme d’installation de classe ne doit jamais tenter de remplacer les opérations du gestionnaire par défaut.

Pour plus d’informations sur l’appel du gestionnaire par défaut, consultez Appel de gestionnaires de code DIF par défaut.

Si le programme d’installation de classe rencontre une erreur, le programme d’installation doit retourner un code d’erreur Win32 approprié et SetupDiCallClassInstaller n’appellera pas par la suite le gestionnaire par défaut.

Un programme d’installation de classe retourne ERROR_DI_BAD_PATH si le membre DriverPath de la structure SP_DEVINSTALL_PARAMS correspondante n’est pas égal à NULL, mais qu’il n’existe aucun pilote valide à l’emplacement de chemin spécifié. Cela peut se produire s’il n’y a pas de pilotes à l’emplacement du chemin d’accès ou s’il existe des pilotes, mais que le membre Indicateurs de la structure SP_DRVINSTALL_PARAMS de chaque pilote a été défini avec l’indicateur DN_BAD_DRIVER. En réponse à ce code d’erreur, Windows affiche une erreur à l’utilisateur.

Gestionnaire de code DIF par défaut

SetupDiSelectDevice

Opération du programme d’installation

En réponse à une demande de DIF_SELECTDEVICE, un programme d’installation effectue toutes les opérations de sélection requises pour son appareil ou sa classe d’appareil, en plus de ce que fait le gestionnaire par défaut. Un programme d’installation répond généralement à cette demande DIF de l’une des manières suivantes :

Ne rien faire.

Si un programme d’installation n’a aucune exigence de sélection spéciale, il ne répond pas à ce code DIF. Un programme d’installation de classe retourne ERROR_DI_DO_DEFAULT et un co-programme d’installation retourne NO_ERROR.
Fournissez les chaînes de sélection que Windows affichera dans l’interface utilisateur de sélection.

Un programme d’installation peut fournir des chaînes de sélection dans les paramètres d’installation de classe (SP_SELECTDEVICE_PARAMS). Par exemple, un programme d’installation peut modifier les instructions ou le titre de l’en-tête de fenêtre.

Un programme d’installation de classe ne doit pas fournir de chaînes de sélection si un co-programme d’installation a déjà fourni des chaînes de sélection. Le co-programme d’installation dispose probablement d’informations plus pertinentes.

Si un programme d’installation modifie le SP_SELECTDEVICE_PARAMS, il doit également définir l’indicateur DI_USECI_SELECTSTRINGS dans le SP_DEVINSTALL_PARAMS.

Si un programme d’installation fournit correctement des chaînes de sélection, Windows doit toujours appeler le gestionnaire par défaut. Par conséquent, dans ce cas, un co-programme d’installation retourne NO_ERROR et un programme d’installation de classe retourne ERROR_DI_DO_DEFAULT.
Modifiez les paramètres d’installation de l’appareil.

Un programme d’installation peut modifier les paramètres d’installation de l’appareil (SP_DEVINSTALL_PARAMS). Par exemple, un programme d’installation peut définir l’indicateur DI_SHOWOEM pour que Windows affiche le bouton Avoir un disque .

Si un programme d’installation de classe modifie correctement les paramètres d’installation de l’appareil, le programme d’installation de classe retourne ERROR_DI_DO_DEFAULT.
Modifiez la liste des pilotes à partir desquels l’utilisateur peut sélectionner.

Cette action est moins courante, mais possible. Un programme d’installation qui modifie la liste des pilotes peut également, ou non, fournir des chaînes de sélection.

Un programme d’installation qui modifie la liste des pilotes marque généralement le ou les pilotes qui ne sont pas appropriés pour l’appareil. Un programme d’installation marque ces pilotes avec l’indicateur DNF_BAD_DRIVER. Windows omet ces pilotes de la liste qu’il affiche à l’utilisateur.

Un programme d’installation marque les pilotes incorrects en procédant comme suit :
1. Créez la liste des pilotes en appelant SetupDiBuildDriverInfoList avec un DriverType de SPDIT_CLASSDRIVER.
2. Obtenez les informations sur le premier pilote de la liste en appelant SetupDiEnumDriverInfo et SetupDiGetDriverInstallParams. Si le pilote n’est pas approprié pour l’appareil, définissez l’indicateur DNF_BAD_DRIVER dans le champ Indicateurs des paramètres. Appliquez la modification aux paramètres en appelant SetupDiSetDriverInstallParams.
3. Répétez l’étape précédente jusqu’à ce que vous ayez traité tous les pilotes de la liste. Veillez à incrémenter le paramètre MemberIndex en SetupDiEnumDriverInfo comme décrit dans la page de référence de cette fonction.
Un programme d’installation peut définir l’indicateur DNF_BAD_DRIVER pour un ou plusieurs pilotes dans la liste des pilotes, mais un programme d’installation ne doit pas effacer cet indicateur.

Si un ou plusieurs programmes d’installation modifient correctement la liste des pilotes, Windows doit toujours appeler le gestionnaire par défaut. Par conséquent, dans ce cas, un co-programme d’installation retourne NO_ERROR et un programme d’installation de classe retourne ERROR_DI_DO_DEFAULT.
Affichez sa propre interface utilisateur de sélection de pilotes et définissez le pilote sélectionné.

Seul un programme d’installation de classe peut afficher sa propre interface utilisateur de sélection de pilotes ; les co-programmes d’installation ne doivent pas. Par exemple, un programme d’installation de classe peut afficher des images au lieu de listes textuelles.

Si le programme d’installation de classe définit correctement le pilote sélectionné, le programme d’installation de classe retourne NO_ERROR et Windows n’appelle pas le gestionnaire par défaut et n’affiche donc pas l’interface de sélection par défaut.

Si l’indicateur DI_ENUMSINGLEINF est défini dans les paramètres d’installation de l’appareil, driverPath est un chemin d’accès d’un seul fichier INF au lieu d’un chemin d’accès d’un répertoire. Un programme d’installation doit utiliser uniquement ce seul INF pour générer la liste des pilotes.

Pour plus d’informations sur les codes DIF, consultez Gestion des codes DIF.