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 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_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
Constantes d'attributs de fichier