UpdateDriverForPlugAndPlayDevicesA, fonction (newdev.h)

Article
08/25/2023

Avec un fichier INF et un ID matériel, la fonction UpdateDriverForPlugAndPlayDevices installe les pilotes mis à jour pour les appareils qui correspondent à l’ID matériel.

Syntaxe

BOOL UpdateDriverForPlugAndPlayDevicesA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR HardwareId,
  [in]            LPCSTR FullInfPath,
  [in]            DWORD  InstallFlags,
  [out, optional] PBOOL  bRebootRequired
);

Paramètres

[in, optional] hwndParent

Handle vers la fenêtre de niveau supérieur à utiliser pour toute interface utilisateur liée à l’installation d’appareils.

[in] HardwareId

Pointeur vers une chaîne terminée par NULL qui fournit l’identificateur matériel pour correspondre aux appareils existants sur l’ordinateur. La longueur maximale d’un identificateur matériel terminé par NULL est MAX_DEVICE_ID_LEN. Pour plus d’informations sur les identificateurs matériels, consultez Chaînes d’identification des appareils.

[in] FullInfPath

Pointeur vers une chaîne terminée par NULL qui fournit le nom de fichier de chemin d’accès complet d’un fichier INF. Les fichiers doivent se trouver sur le support de distribution ou dans un répertoire créé par le fournisseur, et non dans un emplacement système tel que %SystemRoot%\inf. UpdateDriverForPlugAndPlayDevices copie les fichiers de pilote aux emplacements système appropriés si l’installation réussit.

[in] InstallFlags

Valeur fournie par l’appelant créée à l’aide de OR pour combiner zéro ou plusieurs des indicateurs de bits suivants :

INSTALLFLAG_FORCE

Si cet indicateur est défini et que la fonction trouve un appareil qui correspond à la valeur HardwareId , la fonction installe de nouveaux pilotes pour le périphérique si de meilleurs pilotes existent déjà sur l’ordinateur.

Important Utilisez cet indicateur uniquement avec une extrême prudence. La définition de cet indicateur peut entraîner l’installation d’un pilote plus ancien sur un pilote plus récent si un utilisateur exécute l’application du fournisseur une fois les pilotes plus récents disponibles.

INSTALLFLAG_READONLY

Si cet indicateur est défini, la fonction ne copie, ne renomme ni ne supprime les fichiers d’installation. L’utilisation de cet indicateur doit être limitée aux environnements dans lesquels l’accès aux fichiers est limité ou impossible, comme un système d’exploitation « incorporé ».

INSTALLFLAG_NONINTERACTIVE

Si cet indicateur est défini, la fonction retourne FALSE quand une tentative d’affichage de l’interface utilisateur est détectée. Définissez cet indicateur uniquement si la fonction est appelée à partir d’un composant (tel qu’un service) qui ne peut pas afficher l’interface utilisateur.

Note Si cet indicateur est défini et qu’une tentative d’affichage de l’interface utilisateur est effectuée, l’appareil peut être laissé dans un état indéterminé.

Le paramètre InstallFlags est généralement égal à zéro.

[out, optional] bRebootRequired

Pointeur vers une variable de type BOOL qui indique si un redémarrage est requis et qui doit l’inviter. Ce pointeur est facultatif et peut être NULL.

Si le pointeur a la valeur NULL, UpdateDriverForPlugAndPlayDevices demande un redémarrage après l’installation des pilotes, si nécessaire. Si le pointeur est fourni, la fonction retourne une valeur BOOLEAN qui est TRUE si le système doit être redémarré. Il incombe ensuite à l’appelant d’inviter à redémarrer.

Pour plus d’informations, consultez la section Notes suivante.

Valeur retournée

La fonction retourne TRUE si un appareil a été mis à niveau vers le pilote spécifié.

Sinon, elle retourne FALSE et l’erreur journalisée peut être récupérée avec un appel à GetLastError. Les valeurs d’erreur possibles retournées par GetLastError sont incluses dans le tableau suivant.

Code de retour	Description
ERROR_FILE_NOT_FOUND	Le chemin spécifié pour FullInfPath n’existe pas.
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é.
ERROR_INVALID_FLAGS	La valeur spécifiée pour InstallFlags n’est pas valide.
ERROR_NO_SUCH_DEVINST	La valeur spécifiée pour HardwareId ne correspond à aucun appareil sur le système. Autrement dit, l’appareil n’est pas branché.
ERROR_NO_MORE_ITEMS	La fonction a trouvé une correspondance pour la valeur HardwareId , mais le pilote spécifié n’était pas une meilleure correspondance que le pilote actuel et l’appelant n’a pas spécifié l’indicateur INSTALLFLAG_FORCE.

Remarques

UpdateDriverForPlugAndPlayDevices analyse les appareils sur le système et tente d’installer les pilotes spécifiés par FullInfPath pour tous les appareils qui correspondent à la valeur HardwareId spécifiée.

Le comportement par défaut consiste à installer uniquement les pilotes spécifiés s’ils correspondent mieux que les pilotes actuellement installés et les pilotes spécifiés sont également une meilleure correspondance que les pilotes dans %SystemRoot%\inf. Pour plus d’informations, consultez Comment Windows sélectionne les pilotes.

UpdateDriverForPlugAndPlayDevices peut également être utilisé pour déterminer si l’appareil avec la valeur HardwareId spécifiée est branché. Pour plus d’informations, consultez Écriture d’une application d’installation d’appareil.

UpdateDriverForPlugAndPlayDevices envoie une demande de IRP_MN_QUERY_REMOVE_DEVICE à l’appareil spécifié, à tous les enfants de l’appareil et à tous les autres appareils qui font partie de manière récursive des relations de suppression pour l’appareil. Si l’un de ces appareils échoue à une demande de suppression de requête, UpdateDriverForPlugAndPlayDevices définit l’indicateur DI_NEEDREBOOT dans le membre Indicateurs de la structure SP_DEVINSTALL_PARAMS de l’appareil. Pour plus d’informations sur les relations de suppression, consultez la demande IRP_MN_QUERY_DEVICE_RELATIONS .

En règle générale, les applications d’installation d’appareil doivent fournir null pour bRebootRequired. Ainsi, le système lance un redémarrage si nécessaire. Une application doit spécifier une valeur de pointeur uniquement dans les cas suivants :

L’application doit appeler UpdateDriverForPlugAndPlayDevices plusieurs fois pour terminer une installation.
L’application doit effectuer d’autres opérations avant le redémarrage (si nécessaire).
L’application est un programme d’installation de classe, qui doit définir DI_NEEDREBOOT dans SP_DEVINSTALL_PARAMS si un redémarrage est nécessaire.

Si l’application doit appeler UpdateDriverForPlugAndPlayDevices plusieurs fois, elle doit enregistrer tout redémarrage TRUE status valeur reçue, puis demander un redémarrage après le retour de l’appel final.

Si la fonction retourne ERROR_IN_WOW64 dans une application 32 bits, l’application s’exécute sur un système 64 bits, ce qui n’est pas autorisé. Pour plus d’informations, consultez Installation d’appareils sur des systèmes 64 bits.

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	newdev.h (include Newdev.h)
Bibliothèque	Newdev.lib

Partager via