Partager via

Fonction DiInstallDriverW (newdev.h)

  • Article

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 DiInstallDriverW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR 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 (les indicateurs sont généralement définis sur zéro).

Si Flags est égal à zéro, DiInstallDriver installe uniquement le pilote spécifié sur un appareil si le pilote correspond mieux à un appareil 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 Flags inclut DIIRFLAG_FORCE_INF, DiInstallDriver installe le pilote spécifié sur un appareil correspondant, que le pilote corresponde mieux ou non à l’appareil 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 Flags 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 installera tous les fichiers INF dans ce répertoire avec un comportement spécial. Tous les packages de pilotes seront mis en scène dans le magasin de pilotes, mais ne seront pas encore disponibles pour être installés sur les appareils. Lors de l’arrêt suivant du système, ces packages de pilotes seront disponibles pour être installés sur les appareils à l’avenir et ils seront installés sur tous les appareils pour lesquels ils correspondent le mieux pour que les appareils soient prêts au prochain démarrage du système.

[out, optional] NeedReboot

Pointeur vers une valeur de type BOOL que DiInstallDriver définit pour indiquer si un redémarrage du système 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 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 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 ne dispose 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 Flags 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 :

  1. Préinstalle le package de pilotes dans le magasin de pilotes. S’il existe un 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.
  2. Énumère les appareils présents dans le système.
  3. Si indicateurs est égal à zéro, installe le pilote sur un appareil uniquement si le pilote spécifié correspond mieux à l’appareil que le pilote actuellement installé sur l’appareil.
  4. 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, si c’est le cas, 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 nécessaire, 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, auquel cas, le programme d’installation de classe doit définir l’indicateur DI_NEEDREBOOT dans le membre Flags 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 comme un 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. Le mélange 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 (inclure Newdev.h)
Bibliothèque Newdev.lib

Voir aussi

DiInstallDevice