CopyFileW, fonction (winbase.h)

Article
11/20/2024

Copie un fichier existant dans un nouveau fichier.

La fonction CopyFileEx fournit deux fonctionnalités supplémentaires. CopyFileEx pouvez 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 CopyFileW(
  [in] LPCWSTR lpExistingFileName,
  [in] LPCWSTR 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 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, copyFile échoue et GetLastError retourne ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

Nom du nouveau fichier.

Pourboire

[in] bFailIfExists

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

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 des informations d’erreur étendues, 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 : 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.

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 que 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 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 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 est 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	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

Exemples

Pour obtenir un exemple, consultez récupération et modification des attributs de fichier.

Note

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. 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