SetupInstallFileExA, fonction (setupapi.h)
[Cette fonction peut être utilisée dans les systèmes d’exploitation indiqués dans la section Configuration requise. Il sera peut-être modifié ou indisponible dans les versions ultérieures. SetupAPI ne doit plus être utilisé pour installer des applications. Utilisez plutôt Windows Installer pour développer des programmes d’installation d’applications. SetupAPI continue d’être utilisé pour installer les pilotes de périphérique.]
La fonction SetupInstallFileEx installe un fichier tel que spécifié par un INFCONTEXT retourné par SetupFindXXXLine ou explicitement par les informations de nom de fichier et de chemin d’accès. Cette fonction est identique à SetupInstallFile, sauf qu’une boOL est retournée qui indique si le fichier était en cours d’utilisation.
Si un fichier est copié, l’appelant de cette fonction doit disposer de privilèges pour écrire dans le répertoire cible.
Syntaxe
WINSETUPAPI BOOL SetupInstallFileExA(
[in] HINF InfHandle,
[in] PINFCONTEXT InfContext,
[in] PCSTR SourceFile,
[in] PCSTR SourcePathRoot,
[in] PCSTR DestinationName,
[in] DWORD CopyStyle,
[in] PSP_FILE_CALLBACK_A CopyMsgHandler,
[in] PVOID Context,
[out] PBOOL FileWasInUse
);
Paramètres
[in] InfHandle
Pointeur facultatif vers le handle vers un fichier INF qui contient les sections SourceDisksNames et SourceDisksFiles. Si des sections spécifiques à la plateforme existent pour le système de l’utilisateur (par exemple, SourceDisksNames.x86 et SourceDisksFiles.x86), la section spécifique à la plateforme est utilisée. Si InfContext n’est pas spécifié et que CopyStyle inclut SP_COPY_SOURCE_ABSOLUTE ou SP_COPY_SOURCEPATH_ABSOLUTE, InfHandle est ignoré.
[in] InfContext
Pointeur facultatif vers le contexte d’une ligne dans une section Copier des fichiers dans un fichier INF. La routine recherche ce fichier dans la section SourceDisksFiles de InfHandle pour obtenir des informations de copie de fichiers. Si InfContext n’est pas spécifié, SourceFile doit être.
[in] SourceFile
Pointeur facultatif vers le nom de fichier (aucun chemin) du fichier à copier. Le fichier est recherché dans la section SourceDisksFiles. Le paramètre SourceFile doit être spécifié si InfContext ne l’est pas. Toutefois, SourceFile est ignoré si InfContext est spécifié.
[in] SourcePathRoot
Pointeur facultatif vers le chemin d’accès racine du fichier à copier (par exemple, A :\ ou F :). Les chemins d’accès de la section SourceDisksNames sont ajoutés à ce chemin. Le paramètre SourcePathRoot est ignoré si CopyStyle inclut l’indicateur SP_COPY_SOURCE_ABSOLUTE.
[in] DestinationName
Pointeur facultatif vers un nouveau nom pour le fichier copié. Si InfContext est spécifié, DestinationName fournit uniquement le nom de fichier (aucun chemin) du fichier cible. Ce paramètre peut être NULL pour indiquer que le fichier cible doit avoir le même nom que le fichier source. Si InfContext n’est pas spécifié, DestinationName fournit le chemin d’accès et le nom de fichier complets de la cible.
[in] CopyStyle
Indicateurs qui contrôlent le comportement de l’opération de copie de fichiers.
Ces indicateurs peuvent être une combinaison des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Supprimez le fichier source en cas de copie réussie. L’appelant n’est pas averti en cas d’échec de la suppression. |
|
Copiez le fichier uniquement si cela remplace un fichier au niveau du chemin de destination. |
|
Examinez chaque fichier copié pour voir si ses ressources de version indiquent qu’il s’agit de la même version ou d’une version non plus récente qu’une copie existante sur la cible.
Les informations de version de fichier utilisées lors des vérifications de version sont celles spécifiées dans les membres dwFileVersionMS et dwFileVersionLS d’une structure VS_FIXEDFILEINFO , telles que renseignées par les fonctions de version. Si l’un des fichiers n’a pas de ressources de version, ou s’il a des informations de version identiques, le fichier source est considéré comme plus récent. Si le fichier source n’est pas plus récent ou égal à la version et que CopyMsgHandler est spécifié, l’appelant est averti et peut annuler la copie. Si CopyMsgHandler n’est pas spécifié, le fichier n’est pas copié. |
|
Examinez chaque fichier copié pour voir si ses ressources de version indiquent qu’il n’est pas plus récent qu’une copie existante sur la cible. Si le fichier source est plus récent mais que la version n’est pas égale à la cible existante, le fichier est copié. |
|
Vérifiez si le fichier cible existe et, le cas échéant, informez l’appelant qui peut opposer son veto à la copie. Si CopyMsgHandler n’est pas spécifié, le fichier n’est pas remplacé. |
|
Ne décompressez pas le fichier. Lorsque cet indicateur est défini, le fichier cible ne reçoit pas la forme non compressée du nom source (le cas échéant). Par exemple, la copie de « f :\x86\cmd.ex_ » dans « \\install\temp » génère un fichier cible « \\install\temp\cmd.ex_ ». Si l’indicateur SP_COPY_NODECOMP n’a pas été spécifié, le fichier est décompressé et la cible est appelée « \\install\temp\cmd.exe ». La partie nom de fichier de DestinationName, si elle est spécifiée, est supprimée et remplacée par le nom de fichier du fichier source. Lorsque SP_COPY_NODECOMP est spécifié, aucune information de langue ou de version ne peut être vérifiée. |
|
Examinez chaque fichier copié pour voir si sa langue diffère de la langue d’un fichier existant déjà sur la cible. Si c’est le cas et que CopyMsgHandler est spécifié, l’appelant est averti et peut annuler la copie. Si CopyMsgHandler n’est pas spécifié, le fichier n’est pas copié. |
|
SourceFile est un chemin d’accès source complet. Ne le recherchez pas dans la section SourceDisksNames du fichier INF. |
|
SourcePathRoot est la partie de chemin d’accès complet du fichier source. Ignorez la source relative spécifiée dans la section SourceDisksNames du fichier INF du média source où se trouve le fichier. Cet indicateur est ignoré si SP_COPY_SOURCE_ABSOLUTE est spécifié. |
|
Si la cible existe, se comporter comme si elle était en cours d’utilisation et mettre en file d’attente le fichier pour la copie au prochain redémarrage du système. |
|
Si le fichier a été utilisé pendant l’opération de copie, avertissez l’utilisateur que le système nécessite un redémarrage. |
|
Ne donnez pas à l’utilisateur la possibilité d’ignorer un fichier. |
|
Vérifiez si le fichier cible existe et, si c’est le cas, le fichier n’est pas remplacé. L’appelant n’est pas averti. |
|
Examinez chaque fichier copié pour voir si ses ressources de version (ou les horodatages pour les fichiers non image) indiquent qu’il n’est pas plus récent qu’une copie existante sur la cible. Si le fichier copié n’est pas plus récent, le fichier n’est pas copié. L’appelant n’est pas averti. |
|
Si l’utilisateur tente d’ignorer un fichier, avertissez-le que le fait d’ignorer un fichier peut affecter l’installation. (Utilisé pour les fichiers critiques du système.) |
[in] CopyMsgHandler
Pointeur facultatif vers une fonction de rappel pour être informé des différentes conditions qui peuvent survenir pendant la copie de fichier.
[in] Context
Pointeur vers une valeur définie par l’appelant qui est passée comme premier paramètre de la fonction de rappel.
[out] FileWasInUse
Pointeur vers une variable dans laquelle cette fonction retourne un indicateur qui indique si le fichier a été utilisé. Ce paramètre est obligatoire.
Valeur retournée
Si la fonction réussit, la valeur de retour est une valeur différente de zéro.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Si GetLastError retourne NO_ERROR, l’opération de copie de fichiers n’a pas été effectuée. Le fichier n’a peut-être pas été copié parce que l’opération de copie de fichier était inutile ou parce que la fonction de rappel de fichier a retourné FALSE.
Remarques
Cette API est généralement utilisée lors de l’installation de nouvelles versions de fichiers système susceptibles d’être utilisées. Il met à jour une valeur BOOL qui indique si le fichier était en cours d’utilisation. Si le fichier était en cours d’utilisation, l’opération de copie de fichier est reportée jusqu’à ce que le système soit redémarré.
Si un répertoire UNC est spécifié comme répertoire cible d’une installation de fichier, vous devez vous assurer qu’il existe avant d’appeler SetupInstallFileEx. Les fonctions d’installation ne case activée pas pour l’existence de répertoires UNC et ne créent pas de répertoires UNC. Si le répertoire UNC cible n’existe pas, l’installation du fichier échoue.
Notes
L’en-tête setupapi.h définit SetupInstallFileEx 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 | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | setupapi.h |
| Bibliothèque | Setupapi.lib |
| DLL | Setupapi.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour