CopyFileExA, fonction (winbase.h)
Copie un fichier existant dans un nouveau fichier, en informant l’application de sa progression via 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 larges, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez nommage des fichiers, des chemins d’accès et des espaces de noms.
Pourboire
À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précéder « \\ ?\ ». Pour plus d’informations, consultez la section « Limite maximale de longueur de chemin » de noms, fichiers, chemin s et espaces de noms.
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 larges, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez nommage des fichiers, des chemins d’accès et des espaces de noms.
Pourboire
À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précéder « \\ ?\ ». Pour plus d’informations, consultez la section « Limite maximale de longueur de chemin » de noms, fichiers, chemin s et espaces de noms.
[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 continuera à 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 de retour
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 un appel d’informations d’erreur étendu 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 retourne ERROR_REQUEST_ABORTED. Dans ce cas, le fichier de destination partiellement copié est conservé intact.
Remarques
Cette fonction conserve les attributs étendus, le stockage structuré OLE, les flux de données de remplacement du système de fichiers NTFS, les attributs de ressources 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 : attributs de ressources de sécurité (ATTRIBUTE_SECURITY_INFORMATION) pour le fichier existant ne sont pas copiés dans le nouveau fichier tant que Windows 8 et Windows Server 2012 n’ont pas été copiés.
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 : propriétés des ressources de sécurité pour le 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 que 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 cette opération ne peut pas être effectuée, cette fonction tente de chiffrer le fichier de destination avec des 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 CopyFileEx effectuer l’opération de copie même si le fichier de destination ne peut pas être chiffré, incluez l'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, le 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, le 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é, aucun changement de comportement n’est apporté.
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 | Supporté |
|---|---|
| Protocole SMB (Server Message Block) 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 |
| Cluster Shared Volume File System (CsvFS) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
Note
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. 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 | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | winbase.h (inclure Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
constantes d’attribut de fichier