DiInstallDevice, fonction (newdev.h)

Article
08/25/2023

La fonction DiInstallDevice installe un pilote spécifié préinstallé dans le magasin de pilotes sur un appareil spécifié présent dans le système.

Syntaxe

BOOL DiInstallDevice(
  [in, optional]  HWND             hwndParent,
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in, optional]  PSP_DRVINFO_DATA DriverInfoData,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

Paramètres

[in, optional] hwndParent

Handle vers la fenêtre de niveau supérieur que DiInstallDevice utilise pour afficher tout composant d’interface utilisateur associé à l’installation de l’appareil. Ce paramètre est facultatif et peut être défini sur NULL.

[in] DeviceInfoSet

Handle d’un jeu d’informations d’appareil qui contient un élément d’informations sur l’appareil qui représente l’appareil spécifié.

[in] DeviceInfoData

Pointeur vers une structure de SP_DEVINFO_DATA qui représente l’appareil spécifié dans le jeu d’informations de périphérique spécifié.

[in, optional] DriverInfoData

Pointeur vers une structure de SP_DRVINFO_DATA qui spécifie le pilote à installer sur l’appareil spécifié. Ce paramètre est facultatif et peut être défini sur NULL. Si ce paramètre a la valeur NULL, DiInstallDevice recherche dans les pilotes préinstallés dans le magasin de pilotes le pilote qui correspond le mieux à l’appareil spécifié et, le cas échéant, installe le pilote sur l’appareil spécifié.

[in] Flags

Valeur de type DWORD qui spécifie zéro ou l’indicateur suivant :

DIIDFLAG_SHOWSEARCHUI

Si l’appelant ne spécifie pas de pilote (DriverInfoData a la valeur NULL) et Si DiInstallDevice ne trouve pas de pilote préinstallé qui correspond au périphérique spécifié. Au lieu de cela, DiInstallDevice affiche l’Assistant Nouveau matériel trouvé pour l’appareil.

DIIDFLAG_NOFINISHINSTALLUI

DiInstallDevice ne démarre pas les pages de l’Assistant Terminer l’installation ou les actions terminer-installer. L’appelant de DiInstallDevice doit démarrer ces opérations. L’appelant ne doit spécifier cet indicateur que si l’appelant exige que les pages de l’Assistant fin de l’installation soient appelées dans le contexte d’un composant d’interface utilisateur fourni par l’appelant.

DIIDFLAG_INSTALLNULLDRIVER

DiInstallDevice tente d’installer un pilote Null sur l’appareil spécifié. Si cet indicateur est défini, DiInstallDevice n’utilise pas le paramètre DriverInfoData . DiInstallDevice supprime tous les paramètres de l’appareil et, si l’appareil ne peut pas s’exécuter en mode brut, la fonction définit la status de l’appareil sur CM_PROB_FAILED_INSTALL. Si DiInstallDevice ne peut pas installer un pilote Null, l’état résultant de l’appareil est le même que si l’appareil était connecté pour la première fois à l’ordinateur et que Windows n’avait pas trouvé de pilote pour l’appareil.

DIIDFLAG_INSTALLCOPYINFDRIVERS

Tout fichier INF supplémentaire spécifié via une directive CopyINF sera installé sur n’importe quel appareil à lequel il s’applique. Tout échec de l’installation d’un inf supplémentaire n’entraîne pas l’échec de l’installation de l’INF principal.

[out, optional] NeedReboot

Pointeur vers une valeur de type BOOL définie par DiInstallDevice pour indiquer si un redémarrage du système est nécessaire pour terminer l’installation. Ce paramètre est facultatif et peut être défini sur NULL. Si ce paramètre est fourni et qu’un redémarrage du système est nécessaire pour terminer l’installation, DiInstallDevice définit la valeur sur TRUE. Dans ce cas, l’appelant est responsable du redémarrage du système. Si ce paramètre est fourni et qu’un redémarrage du système n’est pas nécessaire, DiInstallDevice définit ce paramètre sur FALSE. Si ce paramètre a la valeur NULL et qu’un redémarrage du système est nécessaire pour terminer l’installation, DiInstallDevice affiche une boîte de dialogue de redémarrage du système.

Valeur retournée

DiInstallDevice retourne TRUE si la fonction a correctement installé le pilote spécifié sur l’appareil spécifié. Sinon, DiInstallDevice retourne FALSE et l’erreur journalisée peut être récupérée en effectuant un appel à GetLastError. Voici quelques-unes des valeurs d’erreur les plus courantes que GetLastError peut retourner :

Code de retour	Description
ERROR_ACCESS_DENIED	L’appelant n’a pas de privilèges d’administrateur. Par défaut, Windows Vista et Windows Server 2008 nécessitent qu’un processus appelant dispose de privilèges d’administrateur pour installer un pilote sur un appareil.
ERROR_INVALID_FLAGS	La valeur spécifiée pour Les indicateurs n’est pas égale à zéro ou au niveau du bit OU des indicateurs valides.
ERROR_IN_WOW64	L’application appelante est une application 32 bits qui tente de s’exécuter dans un environnement 64 bits, ce qui n’est pas autorisé. Pour plus d’informations, consultez Installation d’appareils sur des systèmes 64 bits.

Remarques

Appelez Uniquement DiInstallDevice s’il est nécessaire d’installer un pilote spécifique sur un appareil spécifique. Sinon, utilisez UpdateDriverForPlugAndPlayDevices ou DiInstallDriver pour installer un pilote pour un appareil. Pour plus d’informations sur les fonctions à appeler pour installer un pilote sur un appareil, consultez SetupAPI Functions that Simplifie Driver Installation.

Avant d’appeler DiInstallDevice, l’appelant doit obtenir une structure SP_DEVINFO_DATA pour spécifier l’appareil et, éventuellement, une structure SP_DRVINFO_DATA pour spécifier un pilote pour le périphérique.

Pour créer un jeu d’informations sur l’appareil qui contient l’appareil spécifié et obtenir une structure SP_DEVINFO_DATA pour l’appareil, effectuez l’une des opérations suivantes :

Appelez SetupDiGetClassDevs pour récupérer un jeu d’informations sur l’appareil qui contient l’appareil, puis appelez SetupDiEnumDeviceInfo pour énumérer les appareils dans le jeu d’informations sur l’appareil. À chaque appel, SetupDiEnumDeviceInfo retourne une structure SP_DEVINFO_DATA qui représente l’appareil énuméré dans le jeu d’informations sur l’appareil. Pour obtenir des informations spécifiques sur l’appareil énuméré, appelez SetupDiGetDeviceProperty et fournissez la structure SP_DEVINFO_DATA retournée par SetupDiEnumDeviceInfo.
- - OU -
Appelez SetupDiOpenDeviceInfo pour ajouter un appareil avec un ID de instance d’appareil connu au jeu d’informations sur l’appareil. SetupDiOpenDeviceInfo retourne une structure SP_DEVINFO_DATA qui représente l’appareil dans le jeu d’informations sur l’appareil.

Pour récupérer une structure SP_DRVINFO_DATA pour un pilote sélectionné, appelez SetupDiBuildDriverInfoList afin de créer une liste de pilotes pour le périphérique, puis appelez SetupDiEnumDriverInfo pour énumérer les éléments de la liste des pilotes pour le périphérique. Pour chaque pilote énuméré, SetupDiEnumDriverInfo récupère une structure SP_DRVINFO_DATA qui identifie le pilote. SetupDiGetDriverInfoDetail peut également être appelé pour récupérer des détails supplémentaires sur un pilote énuméré.

En général, une application d’installation doit définir NeedReboot sur NULL. Cela garantit que DiInstallDevice invite l’utilisateur à redémarrer le système si un redémarrage est nécessaire pour terminer l’installation. Une application doit fournir un pointeur NeedReboot uniquement dans les cas suivants :

L’application doit appeler DiInstallDevice plusieurs fois pour terminer une installation. Dans ce cas, l’application doit enregistrer si une valeur TRUENeedReboot est retournée par l’un des appels à DiInstallDevice et, le cas échéant, inviter l’utilisateur à redémarrer le système après le retour de l’appel final à DiInstallDevice .
L’application doit effectuer les opérations requises, autres que l’appel de DiInstallDevice, avant qu’un redémarrage du système ne se produise. Si un redémarrage du système est requis, l’application doit terminer les opérations requises, puis inviter l’utilisateur à redémarrer le système.
L’application est un programme d’installation de classe. Dans ce cas, le programme d’installation de classe doit définir l’indicateur DI_NEEDREBOOT dans le membre Indicateurs de la structure SP_DEVINSTALL_PARAMS d’un appareil.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et les versions plus récentes de Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	newdev.h (include Newdev.h)
Bibliothèque	Newdev.lib
DLL	Newdev.dll