Partager via


Fonction CopyFileExA (winbase.h)

Copie un fichier existant dans un nouveau fichier, en informant l’application de sa progression au moyen d’une fonction de rappel.

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

Syntaxe

BOOL CopyFileExA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags
);

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, la fonction CopyFileEx échoue et la fonction GetLastError retourne ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

Nom du nouveau fichier.

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 .

[in, optional] lpProgressRoutine

Adresse d’une fonction de rappel de type LPPROGRESS_ROUTINE appelée chaque fois qu’une autre partie du fichier a été copiée. Ce paramètre peut être NULL. Pour plus d’informations sur la fonction de rappel de progression, consultez la fonction CopyProgressRoutine .

[in, optional] lpData

Argument à passer à la fonction de rappel. Ce paramètre peut être NULL.

[in, optional] pbCancel

Si cet indicateur est défini sur TRUE pendant l’opération de copie, l’opération est annulée. Sinon, l’opération de copie continue à se terminer.

[in] dwCopyFlags

Indicateurs qui spécifient la façon dont le fichier doit être copié. Ce paramètre peut être une combinaison des valeurs suivantes.

Valeur Signification
COPY_FILE_ALLOW_DECRYPTED_DESTINATION
0x00000008
Une tentative de copie d’un fichier chiffré réussit même si la copie de destination ne peut pas être chiffrée.
COPY_FILE_COPY_SYMLINK
0x00000800
Si le fichier source est un lien symbolique, le fichier de destination est également un lien symbolique pointant vers le même fichier que celui vers lequel pointe le lien symbolique source.

Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.

COPY_FILE_FAIL_IF_EXISTS
0x00000001
L’opération de copie échoue immédiatement si le fichier cible existe déjà.
COPY_FILE_NO_BUFFERING
0x00001000
L’opération de copie est effectuée à l’aide d’E/S non chiffrées, en contournant les ressources du cache d’E/S système. Recommandé pour les transferts de fichiers très volumineux.

Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.

COPY_FILE_OPEN_SOURCE_FOR_WRITE
0x00000004
Le fichier est copié et le fichier d’origine est ouvert pour l’accès en écriture.
COPY_FILE_RESTARTABLE
0x00000002
La progression de la copie est suivie dans le fichier cible en cas d’échec de la copie. La copie ayant échoué peut être redémarrée ultérieurement en spécifiant les mêmes valeurs pour lpExistingFileName et lpNewFileName que celles utilisées dans l’appel qui a échoué. Cela peut ralentir considérablement l’opération de copie, car le nouveau fichier peut être vidé plusieurs fois au cours de l’opération de copie.
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC
0x10000000

Demandez au canal de transfert sous-jacent de compresser les données pendant l’opération de copie. La demande peut ne pas être prise en charge pour tous les supports, auquel cas elle est ignorée. Les attributs et paramètres de compression (complexité de calcul, utilisation de la mémoire) ne sont pas configurables via cette API et peuvent être modifiés entre différentes versions du système d’exploitation.

Cet indicateur a été introduit dans Windows 10, version 1903 et Windows Server 2022. Sur Windows 10, l’indicateur est pris en charge pour les fichiers résidant sur des partages SMB, où la version négociée du protocole SMB est SMB v3.1.1 ou version ultérieure.

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

Si lpProgressRoutine retourne PROGRESS_CANCEL en raison de l’annulation de l’opération par l’utilisateur, CopyFileEx retourne zéro et GetLastError retourne ERROR_REQUEST_ABORTED. Dans ce cas, le fichier de destination partiellement copié est supprimé.

Si lpProgressRoutine retourne PROGRESS_STOP en raison de l’arrêt de l’opération par l’utilisateur, CopyFileEx retourne zéro et GetLastError renvoie ERROR_REQUEST_ABORTED. Dans ce cas, le fichier de destination partiellement copié est laissé intact.

Remarques

Cette fonction conserve les attributs étendus, le stockage structuré OLE, les flux de données alternatifs du système de fichiers NTFS, les attributs de ressource de sécurité et les attributs de fichier.

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

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.

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 des fichiers chiffrés sont copiés à l’aide de CopyFileEx, la fonction 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 ces deux méthodes ne peuvent pas être effectuées, CopyFileEx échoue avec un code d’erreur ERROR_ENCRYPTION_FAILED . Si vous souhaitez que CopyFileEx termine l’opération de copie même si le fichier de destination ne peut pas être chiffré, incluez le COPY_FILE_ALLOW_DECRYPTED_DESTINATION comme valeur du paramètre dwCopyFlags dans votre appel à CopyFileEx.

Si COPY_FILE_COPY_SYMLINK est spécifié, les règles suivantes s’appliquent :

  • Si le fichier source est un lien symbolique, ce lien symbolique est copié, et non le fichier cible.
  • Si le fichier source n’est pas un lien symbolique, il n’y a aucun changement de comportement.
  • Si le fichier de destination est un lien symbolique existant, ce lien symbolique est remplacé, et non le fichier cible.
  • Si COPY_FILE_FAIL_IF_EXISTS est également spécifié et que le fichier de destination est un lien symbolique existant, l’opération échoue dans tous les cas.
Si COPY_FILE_COPY_SYMLINK n’est pas spécifié, les règles suivantes s’appliquent :
  • Si COPY_FILE_FAIL_IF_EXISTS est également spécifié et que le fichier de destination est un lien symbolique existant, l’opération échoue uniquement si la cible du lien symbolique existe.
  • Si COPY_FILE_FAIL_IF_EXISTS n’est pas spécifié, il n’y a aucun changement de comportement.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Si vous écrivez une application qui optimise les opérations de copie de fichiers sur un réseau local, envisagez d’utiliser la fonction TransmitFile à partir de Windows Sockets (Winsock). TransmitFile prend en charge les transferts réseau hautes performances et fournit une interface simple pour envoyer le contenu d’un fichier à un ordinateur distant. Pour utiliser TransmitFile, vous devez écrire une application cliente Winsock qui envoie le fichier à partir de l’ordinateur source, ainsi qu’une application serveur Winsock qui utilise d’autres fonctions Winsock pour recevoir le fichier sur l’ordinateur distant.

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
 

Notes

L’en-tête winbase.h définit CopyFileEx 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

Voir aussi

CopyFile

CopyFileTransacted

CopyProgressRoutine

CreateFile

Constantes d'attributs de fichier

Fonctions de gestion des fichiers

MoveFile

MoveFileWithProgress

Liens symboliques

TransmitFile