CopyFileA, fonction (winbase.h)

Article
03/06/2024

Copie un fichier existant vers un nouveau fichier.

La fonction CopyFileEx fournit deux fonctionnalités supplémentaires. CopyFileEx peut appeler une fonction de rappel spécifiée chaque fois qu’une partie de l’opération de copie est terminée, et CopyFileEx peut être annulé pendant l’opération de copie.

Pour effectuer cette opération en tant qu’opération transactionnelle, utilisez la fonction CopyFileTransacted .

Syntaxe

BOOL CopyFileA(
  [in] LPCSTR lpExistingFileName,
  [in] LPCSTR lpNewFileName,
  [in] BOOL   bFailIfExists
);

Paramètres

[in] lpExistingFileName

Nom d’un fichier existant.

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères de large, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.

Conseil

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation de MAX_PATH sans précédencer « \ ?\ ». Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans Naming Files, Paths et Namespaces .

Si lpExistingFileName n’existe pas, CopyFile échoue et GetLastError retourne ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

Nom du nouveau fichier.

Conseil

[in] bFailIfExists

Si ce paramètre a la valeur TRUE et que le nouveau fichier spécifié par lpNewFileName existe déjà, la fonction échoue. Si ce paramètre a la valeur FALSE et que le nouveau fichier existe déjà, la fonction remplace le fichier existant et réussit.

Valeur retournée

Si la fonction réussit, la valeur de retour est 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.

Remarques

Les propriétés de ressource de sécurité (ATTRIBUTE_SECURITY_INFORMATION) du fichier existant sont copiées dans le nouveau fichier.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Les propriétés de ressource de sécurité du fichier existant ne sont pas copiées dans le nouveau fichier tant que Windows 8 et Windows Server 2012.

Les attributs de fichier pour le fichier existant sont copiés dans le nouveau fichier. Par exemple, si un fichier existant a l’attribut de fichier FILE_ATTRIBUTE_READONLY , une copie créée par le biais d’un appel à CopyFile aura également l’attribut de fichier FILE_ATTRIBUTE_READONLY . Pour plus d’informations, consultez Récupération et modification des attributs de fichier.

Cette fonction échoue avec ERROR_ACCESS_DENIED si le fichier de destination existe déjà et si l’attribut FILE_ATTRIBUTE_HIDDEN ou FILE_ATTRIBUTE_READONLY est défini.

Lorsque CopyFile est utilisé pour copier un fichier chiffré, il tente de chiffrer le fichier de destination avec les clés utilisées dans le chiffrement du fichier source. Si cela ne peut pas être fait, cette fonction tente de chiffrer le fichier de destination avec les clés par défaut. Si aucune de ces méthodes ne peut être effectuée, CopyFile échoue avec un code d’erreur ERROR_ENCRYPTION_FAILED .

Comportement de lien symbolique : si le fichier source est un lien symbolique, le fichier réel copié est la cible du lien symbolique.

Si le fichier de destination existe déjà et qu’il s’agit d’un lien symbolique, la cible du lien symbolique est remplacée par le fichier source.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Prise en charge
Protocole Server Message Block (SMB) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Oui
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Exemples

Pour obtenir un exemple, consultez Récupération et modification d’attributs de fichier.

Notes

L’en-tête winbase.h définit CopyFile 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. La combinaison 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 \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll