SetupDiInstallDevice, fonction (setupapi.h)

  • Article

La fonction SetupDiInstallDevice est le gestionnaire par défaut pour la demande d’installation DIF_INSTALLDEVICE .

Syntaxe

WINSETUPAPI BOOL SetupDiInstallDevice(
  [in]      HDEVINFO         DeviceInfoSet,
  [in, out] PSP_DEVINFO_DATA DeviceInfoData
);

Paramètres

[in] DeviceInfoSet

Handle de l’ensemble d’informations sur l’appareil pour le système local qui contient un élément d’informations sur l’appareil qui représente l’appareil à installer.

[in, out] DeviceInfoData

Pointeur vers une structure de SP_DEVINFO_DATA qui spécifie un élément d’informations sur l’appareil dans DeviceInfoSet. Il s’agit d’un paramètre IN-OUT, car DeviceInfoData.DevInst peut être mis à jour avec une nouvelle valeur de handle lors du retour.

Valeur retournée

La fonction retourne TRUE si elle réussit. Sinon, elle retourne FALSE et l’erreur journalisée peut être récupérée avec un appel à GetLastError.

Remarques

SetupDiInstallDevice installe un pilote à partir du fichier INF. La définition de « pilote » de SetupAPI est en fait un « nœud de pilote ». Par conséquent, lorsque cette fonction installe un pilote, elle installe également les éléments de la liste suivante :

  • Service(s) pour l’appareil.
  • Fichiers de pilote.
  • Co-programme d’installation spécifique à l’appareil (le cas échéant).
  • Fournisseurs de pages de propriétés (le cas échéant).
  • Applets du panneau de configuration (le cas échéant).
Cette fonction enregistre également toutes les interfaces d’appareil requises.

Une installation réussie comprend, sans s’y limiter, les étapes suivantes :

  • Créez une clé de pilote dans le Registre et écrivez les entrées appropriées (telles que InfPath et ProviderName).
  • Recherchez et traitez la section INF DDInstall pour l’appareil. La section peut être spécifique au système d’exploitation/à l’architecture. Les entrées AddReg et DelReg de la section DDInstall sont dirigées vers la clé logicielle de l’appareil. Recherchez et traitez DDInstall. Section HW dont les entrées AddReg et DelReg sont dirigées vers la clé matérielle de l’appareil. Recherchez et traitez la section INF DDInstall.LogConfigOverride, le cas échéant, pour fournir une configuration de remplacement pour l’appareil. Recherchez et traitez la section INF DDInstall.Services pour ajouter des services pour l’appareil (et éventuellement supprimer les anciens services qui ne sont plus nécessaires).
  • Copiez le fichier INF dans le répertoire INF système.
  • Effectuez éventuellement les autres opérations de fichier, en fonction des paramètres d’indicateur dans les paramètres d’installation de l’appareil.

    Si l’indicateur DI_NOFILECOPY et l’indicateur DI_NOVCP sont clairs, effectuez les opérations de fichier spécifiées dans la section DDInstall . Si l’indicateur DI_NOVCP est défini, les opérations de fichier sont mises en file d’attente.

    Si l’indicateur DI_NOFILECOPY est défini, ne copiez pas les fichiers. Cet indicateur peut être défini si, par exemple, une opération de DIF_INSTALLDEVICEFILES a déjà été effectuée pour cette installation de l’appareil.

  • Chargez les pilotes de l’appareil. Cela inclut le pilote de fonction et tous les pilotes de filtre supérieur ou inférieur.
  • Appelez les routines AddDevice des pilotes.
  • Démarrez l’appareil en envoyant un paquet de demande d’E /S (IRP) IRP_MN_START_DEVICE.
Windows ne démarre pas l’appareil si l’indicateur DI_NEEDRESTART, DI_NEEDREBOOT ou DI_DONOTCALLCONFIGMG est défini dans la structure SP_DEVINSTALL_PARAMS .

Un programme d’installation de classe doit retourner ERROR_DI_DO_DEFAULT ou appeler cette fonction lors de la gestion d’une demande de DIF_INSTALLDEVICE . Cette fonction effectue de nombreuses tâches pour l’installation de l’appareil et cette liste de tâches peut être étendue dans les versions ultérieures. Si un programme d’installation de classe effectue l’installation de l’appareil sans appeler cette fonction, le programme d’installation de classe peut ne pas fonctionner correctement sur les versions futures du système d’exploitation.

Si Windows ne peut pas localiser un fichier INF pour l’appareil, il envoie DIF_INSTALLDEVICE dans une tentative d’installation d’un pilote Null. SetupDiInstallDevice installe un pilote Null uniquement si l’appareil prend en charge le mode brut ou s’il s’agit d’un appareil non PnP (signalé par IoReportDetectedDevice). Pour plus d’informations, consultez DIF_INSTALLDEVICE.

Si l’indicateur DI_FLAGSEX_SETFAILEDINSTALL est défini dans la structure SP_DEVINSTALL_PARAMS , SetupDiInstallDevice définit simplement l’indicateur FAILEDINSTALL dans la valeur de Registre ConfigFlags de l’appareil.

Note Seul un programme d’installation de classe doit appeler SetupDiInstallDevice et uniquement dans les situations où le programme d’installation de classe doit effectuer des opérations d’installation d’appareil après que SetupDiInstallDevice a terminé l’opération d’installation de l’appareil par défaut. Dans de telles situations, le programme d’installation de classe doit appeler directement SetupDiInstallDevice quand le programme d’installation traite une demande de DIF_INSTALLDEVICE. Pour plus d’informations sur l’appel du gestionnaire par défaut, consultez Appel des gestionnaires de code DIF par défaut.
 
L’appelant de SetupDiInstallDevice doit être membre du groupe Administrateurs.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows.
Plateforme cible Desktop (Expérience utilisateur)
En-tête setupapi.h (inclure Setupapi.h)
Bibliothèque Setupapi.lib
DLL Setupapi.dll

Voir aussi

DIF_INSTALLDEVICE

SetupDiCallClassInstaller

SetupDiInstallDriverFiles