CopyFileTransactedW, fonction (winbase.h)

Article
03/06/2024

[Microsoft recommande vivement aux développeurs d’utiliser d’autres moyens pour répondre aux besoins de votre application. De nombreux scénarios utilisant TxF peuvent être réalisés à l’aide de techniques plus simples et plus facilement disponibles. En outre, TxF peut ne pas être disponible dans les versions à venir de Microsoft Windows. Pour plus d’informations et les alternatives à TxF, consultez Alternatives à l’utilisation de Transactionnel NTFS.]

Copie un fichier existant dans un nouveau fichier dans le cadre d’une opération transactionnelle, en informant l’application de sa progression au moyen d’une fonction de rappel.

Syntaxe

BOOL CopyFileTransactedW(
  [in]           LPCWSTR            lpExistingFileName,
  [in]           LPCWSTR            lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags,
  [in]           HANDLE             hTransaction
);

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

Le fichier doit résider sur l’ordinateur local ; sinon, la fonction échoue et le dernier code d’erreur est défini sur ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] lpNewFileName

Nom du nouveau fichier.

Conseil

[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_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.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	L’opération de copie échoue immédiatement si le fichier cible existe déjà.
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.

[in] hTransaction

Handle de la transaction. Ce handle est retourné par la fonction CreateTransaction .

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, CopyFileTransacted 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, CopyFileTransacted retourne zéro et GetLastError retourne ERROR_REQUEST_ABORTED. Dans ce cas, le fichier de destination partiellement copié est laissé intact.

Si vous tentez d’appeler cette fonction avec un handle pour une transaction qui a déjà été restaurée, CopyFileTransacted retourne ERROR_TRANSACTION_NOT_ACTIVE ou ERROR_INVALID_TRANSACTION.

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 sécurité et les attributs de fichier.

Windows 7, Windows Server 2008 R2, Windows Server 2008 et Windows Vista : 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.

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.

Les fichiers chiffrés ne sont pas pris en charge par TxF.

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.

Le suivi des liens n’est pas pris en charge par TxF.

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	No
Basculement transparent SMB 3.0 (TFO)	No
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	No
Système de fichiers du volume partagé de cluster (CsvFS)	No
Système de fichiers résilient (ReFS)	No

Notez que SMB 3.0 ne prend pas en charge TxF.

Notes

L’en-tête winbase.h définit CopyFileTransacted en tant qu’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 Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll