UpdateDriverForPlugAndPlayDevicesA, fonction (newdev.h)

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.

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.

[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.

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 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