CopyFileTransactedA, fonction (winbase.h)

Article
11/20/2024

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

Copie un fichier existant dans un nouveau fichier en tant qu’opération transactionnelle, en informant l’application de sa progression via une fonction de rappel.

Syntaxe

BOOL CopyFileTransactedA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             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 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 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.

Pourboire

[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	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 ayant échoué. Cela peut ralentir considérablement l’opération de copie, car le nouveau fichier peut être vidé plusieurs fois pendant l’opération de copie.

[in] hTransaction

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

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, 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 conservé intact.

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

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

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

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.

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, 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_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é, aucun changement de comportement n’est apporté.

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	Supporté
Protocole SMB (Server Message Block) 3.0	Non
Basculement transparent SMB 3.0 (TFO)	Non
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Non
Cluster Shared Volume File System (CsvFS)	Non
Système de fichiers résilient (ReFS)	Non

Notez que SMB 3.0 ne prend pas en charge TxF.

Note

L’en-tête winbase.h définit CopyFileTransacted 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 Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll