DiInstallDriverA, fonction (newdev.h)

Article
03/04/2024

La fonction DiInstallDriver préinstalle un pilote dans le magasin de pilotes , puis installe le pilote sur les appareils présents dans le système pris en charge par le pilote.

Syntaxe

BOOL DiInstallDriverA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR InfPath,
  [in]            DWORD  Flags,
  [out, optional] PBOOL  NeedReboot
);

Paramètres

[in, optional] hwndParent

Handle de la fenêtre de niveau supérieur que DiInstallDriver 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] InfPath

Pointeur vers une chaîne terminée par NULL qui fournit le chemin complet du fichier INF pour le package de pilotes.

[in] Flags

Valeur de type DWORD qui spécifie zéro ou une combinaison d’un ou plusieurs indicateurs, comme décrit ici (Indicateurs est généralement défini sur zéro).

Si Indicateurs est égal à zéro, DiInstallDriver installe uniquement le pilote spécifié sur un appareil si le pilote correspond mieux à un périphérique que le pilote actuellement installé sur un appareil. Pour plus d’informations sur la façon dont Windows sélectionne un pilote pour un appareil, consultez Comment Windows sélectionne les pilotes.

Si Indicateurs inclut DIIRFLAG_FORCE_INF, DiInstallDriver installe le pilote spécifié sur un appareil correspondant, que le pilote corresponde mieux ou non au périphérique que le pilote actuellement installé sur l’appareil. Si DIIRFLAG_INSTALL_AS_SET est également spécifié, DIIRFLAG_FORCE_INF est ignoré.

Attention Forcer l’installation du pilote peut entraîner le remplacement d’un pilote plus compatible ou plus récent par un pilote moins compatible ou plus ancien.

Si Indicateurs inclut DIIRFLAG_INSTALL_AS_SET (pris en charge sur Windows 10 version 1709 et ultérieure), InfPath doit spécifier un répertoire au lieu d’un chemin complet vers un fichier INF et DiInstallDriver installe tous les fichiers INF dans ce répertoire avec un comportement spécial. Tous les packages de pilotes seront mis en lots dans le Magasin des pilotes, mais ne seront pas encore disponibles pour être installés sur les appareils. À l’arrêt suivant du système, ces packages de pilotes seront mis à disposition pour être installés sur les appareils à l’avenir et ils seront installés sur tous les appareils qui correspondent le mieux pour, de sorte que les appareils soient prêts au prochain démarrage du système.

[out, optional] NeedReboot

Pointeur vers une valeur de type BOOL définie par DiInstallDriver pour indiquer si un système est redémarré est nécessaire pour terminer l’installation. Ce paramètre est facultatif et peut être NULL. Si le paramètre est fourni et qu’un redémarrage du système est nécessaire pour terminer l’installation, DiInstallDriver définit la valeur sur TRUE. Dans ce cas, l’appelant doit inviter l’utilisateur à redémarrer le système. Si ce paramètre est fourni et qu’un redémarrage du système n’est pas nécessaire pour terminer l’installation, DiInstallDriver définit la valeur sur FALSE. Si le paramètre a la valeur NULL et qu’un redémarrage du système est nécessaire pour terminer l’installation, DiInstallDriver affiche une boîte de dialogue de redémarrage du système. Pour plus d’informations sur ce paramètre, consultez la section Remarques suivante.

Valeur retournée

DiInstallDriver retourne TRUE si la fonction a correctement préinstallé le package de pilotes spécifié dans le magasin de pilotes. DiInstallDriver retourne également TRUE si la fonction a correctement installé le pilote sur un ou plusieurs appareils du système. Si le package de pilotes n’est pas correctement installé dans le magasin de pilotes, DiInstallDriver retourne FALSE et l’erreur journalisée peut être récupérée en appelant 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 exige que l’appelant dispose de privilèges d’administrateur pour préinstaller un package de pilotes dans le magasin de pilotes.
ERROR_FILE_NOT_FOUND	Le chemin du fichier INF spécifié n’existe pas.
ERROR_INVALID_FLAGS	La valeur spécifiée pour Les indicateurs n’est pas égale à zéro ou DIIRFLAG_FORCE_INF.
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

DiInstallDriver effectue les opérations suivantes :

Préinstalle le package de pilotes dans le magasin de pilotes. S’il existe une instance du même package de pilotes déjà préinstallé dans le magasin de pilotes, DiInstallDriver supprime d’abord cette instance, puis ajoute la nouvelle instance du package de pilotes au magasin de pilotes.
Énumère les appareils présents dans le système.
Si indicateurs est égal à zéro, installe le pilote sur un appareil uniquement si le pilote spécifié correspond mieux au périphérique que le pilote actuellement installé sur l’appareil.
Si Indicateurs est égal à DIIRFLAG_FORCE_INF, installe le pilote sur un appareil, que le package de pilotes corresponde mieux au périphérique que le pilote actuellement installé sur l’appareil.

En général, une application d’installation doit définir NeedReboot sur NULL pour indiquer à DiInstallDriver d’inviter 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 DiInstallDriver 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 à DiInstallDriver et, le cas échéant, inviter l’utilisateur à redémarrer le système après le retour de l’appel final à DiInstallDriver .
L’application doit effectuer les opérations requises, autres que l’appel de DiInstallDriver, 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.

Pour installer un pilote sélectionné sur un appareil sélectionné, appelez DiInstallDevice. Pour plus d’informations, consultez SetupApi Functions that Simplifie Driver Installation.

Notes

L’en-tête newdev.h définit DiInstallDriver en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

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

Voir aussi

DiInstallDevice

Partager via