UpdateDriverForPlugAndPlayDevicesW, fonction (newdev.h)

  • Article
  • 4 minutes de lecture

Étant donné 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 correspondre aux appareils existants sur l’ordinateur. La longueur maximale d’un identificateur matériel arrêté 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 pilotes aux emplacements système appropriés si l’installation réussit.

[in] InstallFlags

Valeur fournie par l’appelant créé à l’aide d’OR pour combiner zéro ou plusieurs 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 l’appareil si de meilleurs pilotes existent déjà sur l’ordinateur.

Important Utilisez cet indicateur uniquement avec prudence extrême. 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 pas, renomme ou supprime tous les fichiers d’installation. L’utilisation de cet indicateur doit être limitée aux environnements dans lesquels l’accès au fichier est restreint ou impossible, comme un système d’exploitation « incorporé ».

INSTALLFLAG_NONINTERACTIVE

Si cet indicateur est défini, la fonction retourne FALSE lorsque toute tentative d’affichage de l’interface utilisateur est détectée. Définissez cet indicateur uniquement si la fonction sera 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 d’interface utilisateur est tenté, l’appareil peut être laissé dans un état indéterminé.
 
Le paramètre InstallFlags est généralement zéro.

[out, optional] bRebootRequired

Pointeur vers une variable typée 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 est NULL, UpdateDriverForPlugAndPlayDevices invite un redémarrage après l’installation des pilotes, si nécessaire. Si le pointeur est fourni, la fonction retourne une valeur BOOLEAN true si le système doit être redémarré. Il incombe ensuite à l’appelant de demander un redémarrage.

Pour plus d’informations, consultez la section Remarques suivantes.

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 d’s’exécuter dans un environnement 64 bits, 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 connecté.
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.

Notes

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 uniquement à installer les pilotes spécifiés s’ils sont mieux correspondants que les pilotes actuellement installés et que 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ée. Pour plus d’informations, consultez Écriture d’une application d’installation d’appareil.

UpdateDriverForPlugAndPlayDevices envoie une requête IRP_MN_QUERY_REMOVE_DEVICE à l’appareil spécifié, tous les enfants de l’appareil et tous les autres appareils qui font partie 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 Indicateurs de la structure SP_DEVINSTALL_PARAMS de l’appareil. Pour plus d’informations sur les relations de suppression, consultez la requête 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) se produit.
  • 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 une valeur d’état de redémarrage TRUE reçue, puis demander un redémarrage une fois l’appel final retourné.

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

Configuration requise

   
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