UpdateDriverForPlugAndPlayDevicesW, fonction (newdev.h)

  • Article

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

Syntaxe

BOOL UpdateDriverForPlugAndPlayDevicesW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR HardwareId,
  [in]            LPCWSTR 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 qu’il corresponde 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 d’appareil.

[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 recherche un appareil qui correspond à la valeur HardwareId , la fonction installe de nouveaux pilotes pour l’appareil 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 copiera, ne renommera ni ne supprimera aucun fichier d’installation. L’utilisation de cet indicateur doit être limitée aux environnements dans lesquels l’accès aux fichiers est restreint ou impossible, comme un système d’exploitation « incorporé ».

INSTALLFLAG_NONINTERACTIVE

Si cet indicateur est défini, la fonction retourne FALSE lorsqu’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’un affichage de l’interface utilisateur est tenté, 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 nécessaire et qui doit l’inviter. Ce pointeur est facultatif et peut avoir la valeur 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 Remarques suivante.

Valeur retournée

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

Sinon, il 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 les pilotes spécifiés uniquement s’ils correspondent mieux que les pilotes actuellement installés et que les pilotes spécifiés correspondent également mieux que tous 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 de 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 Flags de la structure SP_DEVINSTALL_PARAMS pour 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. Par conséquent, le système lancera 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 que le redémarrage (si nécessaire) ne se produise.
  • 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 (inclure Newdev.h)
Bibliothèque Newdev.lib