SetupInstallFileA, fonction (setupapi.h)

Article
11/20/2024

[Cette fonction est disponible pour une utilisation dans les systèmes d’exploitation indiqués dans la section Configuration requise. Il 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 des pilotes de périphérique.]

La fonction SetupInstallFile installe un fichier tel que spécifié par un INFCONTEXT retourné par SetupFindXXXLine ou explicitement par le nom et le chemin d’accès du fichier.

Si un fichier est copié, l’appelant de cette fonction doit disposer de privilèges d’écriture dans le répertoire cible.

Syntaxe

WINSETUPAPI BOOL SetupInstallFileA(
  [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
);

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 est null 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 fichier. Si InfHandle n’est pas spécifié, SourceFile doit être.

[in] SourceFile

Pointeur facultatif vers le nom de fichier (pas de chemin d’accès) du fichier à copier. Le fichier est recherché dans la section SourceDisksFiles. Le paramètre SourceFile doit être spécifié si InfContext n’est pas. SourceFile est ignoré si InfContext est spécifié.

[in] SourcePathRoot

Pointeur facultatif vers le chemin 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 de SP_COPY_SOURCE_ABSOLUTE.

[in] DestinationName

Pointeur facultatif vers le nom de fichier uniquement (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 complet et le nom de fichier de la cible.

[in] CopyStyle

Indicateurs qui contrôlent le comportement de l’opération de copie de fichier. Ces indicateurs peuvent être une combinaison des valeurs suivantes.

Valeur	Signification
SP_COPY_DELETESOURCE	Supprime le fichier source lors de la copie réussie. L’appelant n’est pas averti si l’opération de suppression échoue.
SP_COPY_REPLACEONLY	Copie le fichier uniquement si cela remplacerait un fichier au niveau du chemin d’accès de destination. Si la cible n’existe pas, la fonction retourne FALSE et GetLastError retourne NO_ERROR.
SP_COPY_NEWER_OR_SAME	Examine chaque fichier copié pour voir si ses ressources de version indiquent qu’elle est la même version ou pas 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 spécifiées dans la dwFileVersionMS et membres dwFileVersionLS d’une structure VS_FIXEDFILEINFO, comme renseigné par les fonctions de version. Si l’un des fichiers n’a pas de ressources de version ou s’ils ont 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 dans la version, et CopyMsgHandler est spécifié, l’appelant est averti et peut annuler l’opération de copie. Si copyMsgHandler n’est pas spécifié, le fichier n’est pas copié.
SP_COPY_NEWER_ONLY	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 pas égal à la version de la cible existante, le fichier est copié.
SP_COPY_NOOVERWRITE	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é.
SP_COPY_NODECOMP	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_ vers \\installer\temp génère un fichier cible de \\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 de nom de fichier de DestinationName, si 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 langue ou aucune information de version ne peut être vérifiée.
SP_COPY_LANGUAGEAWARE	Examinez chaque fichier copié pour voir si sa langue diffère de la langue d’un fichier existant déjà sur la cible. Dans ce cas, et 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é.
SP_COPY_SOURCE_ABSOLUTE	sourceFile est un chemin d’accès source complet. Ne recherchez pas dans la section SourceDisksNames du fichier INF.
SP_COPY_SOURCEPATH_ABSOLUTE	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 pour le média source où se trouve le fichier. Cet indicateur est ignoré si SP_COPY_SOURCE_ABSOLUTE est spécifié.
SP_COPY_FORCE_IN_USE	Si la cible existe, se comporte comme si elle était en cours d’utilisation et met en file d’attente le fichier à copier lors du prochain redémarrage du système.
SP_COPY_FORCE_NOOVERWRITE	Vérifie si le fichier cible existe et, le cas échéant, le fichier n’est pas remplacé. L’appelant n’est pas averti.
SP_COPY_FORCE_NEWER	Examine chaque fichier copié pour voir si ses ressources de version (ou 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 en cours de copie n’est pas plus récent, le fichier n’est pas copié. L’appelant n’est pas averti. La fonction retourne FAUX, et GetLastError retourne NO_ERROR.

[in] CopyMsgHandler

Pointeur facultatif vers une fonction de rappel pour être averti de différentes conditions qui peuvent survenir pendant l’opération de copie de fichier.

[in] Context

Pointeur facultatif vers une valeur définie par l’appelant qui est passée en tant que premier paramètre de la fonction de rappel.

Valeur de retour

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’erreur étendues, appelez GetLastError.

Si GetLastError retourne NO_ERROR, l’opération de copie de fichier n’a pas été effectuée. Le fichier n’a peut-être pas été copié, car l’opération de copie de fichier n’était pas nécessaire ou parce que la fonction de rappel de fichier a retourné FALSE.

Remarques

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 SetupInstallFile. Les fonctions d’installation ne vérifient pas l’existence ni la création de répertoires UNC. Si le répertoire UNC cible n’existe pas, l’installation du fichier échoue.

Note

L’en-tête setupapi.h définit SetupInstallFile comme 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	setupapi.h
bibliothèque	Setupapi.lib
DLL	Setupapi.dll