CopyFile2, fonction (winbase.h)

Article
08/27/2023

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

Syntaxe

HRESULT CopyFile2(
  [in]           PCWSTR                        pwszExistingFileName,
  [in]           PCWSTR                        pwszNewFileName,
  [in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);

Paramètres

[in] pwszExistingFileName

Nom d’un fichier existant.

Pour étendre cette limite à 32 767 caractères de large, ajoutez « \? » au chemin. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.

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

Si lpExistingFileName n’existe pas, la fonction CopyFile2 échoue retourne HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND).

[in] pwszNewFileName

Nom du nouveau fichier.

Pour étendre cette limite à 32 767 caractères de large, ajoutez « \? » au chemin. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.

[in, optional] pExtendedParameters

Adresse facultative d’une structure de COPYFILE2_EXTENDED_PARAMETERS .

Valeur retournée

Si la fonction réussit, la valeur de retour retourne TRUE lorsqu’elle est passée à la macro SUCCEEDED .

Code de retour	Description
S_OK	L’opération de copie s’est terminée avec succès.
HRESULT_FROM_WIN32(ERROR_REQUEST_PAUSED)	L’opération de copie a été suspendue par un retour COPYFILE2_PROGRESS_PAUSE de la fonction de rappel CopyFile2ProgressRoutine .
HRESULT_FROM_WIN32(ERROR_REQUEST_ABORTED)	L’opération de copie a été suspendue par un COPYFILE2_PROGRESS_CANCEL ou COPYFILE2_PROGRESS_STOP retour de la fonction de rappel CopyFile2ProgressRoutine .
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)	Le membre dwCopyFlags de la structure COPYFILE2_EXTENDED_PARAMETERS passée par le paramètre pExtendedParameters contient l’indicateur COPY_FILE_FAIL_IF_EXISTS et un nom en conflit existait.
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)	Le membre dwCopyFlags de la structure COPYFILE2_EXTENDED_PARAMETERS passée par le paramètre pExtendedParameters contient l’indicateur COPY_FILE_FAIL_IF_EXISTS et un nom en conflit existait.

Remarques

Cette fonction conserve les attributs étendus, le stockage structuré OLE, les flux de données alternatifs du système de fichiers NTFS et les attributs de fichier. Les attributs de sécurité du fichier existant ne sont pas copiés dans le nouveau fichier. Pour copier des attributs de sécurité, utilisez la fonction SHFileOperation .

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

Pour compiler une application qui utilise cette fonction, définissez la macro _WIN32_WINNT comme _WIN32_WINNT_WIN8 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

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

À compter de Windows 10, version 1903 et Windows Server 2022, une nouvelle valeur, COPY_FILE_REQUEST_COMPRESSED_TRAFFIC, est prise en charge pour le champ dwCopyFlags de la structure COPYFILE2_EXTENDED_PARAMETERS passée dans l’argument pExtendedParameters à cette fonction. Cette nouvelle valeur demande que le canal de transfert sous-jacent compresse 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. 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.

Configuration requise


Client minimal pris en charge	Windows 8 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2012 [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

COPYFILE2_EXTENDED_PARAMETERS

Fonctions de gestion des fichiers

Partager via