CopyFileTransactedA-Funktion (winbase.h)

Artikel
06/02/2023

[Microsoft empfiehlt Entwicklern dringend, alternative Mittel zu verwenden, um die Anforderungen Ihrer Anwendung zu erfüllen. Viele Szenarien, für die TxF entwickelt wurde, können durch einfachere und leichter verfügbare Techniken erreicht werden. Darüber hinaus ist TxF in zukünftigen Versionen von Microsoft Windows möglicherweise nicht verfügbar. Weitere Informationen und Alternativen zu TxF finden Sie unter Alternativen zur Verwendung von Transaktions-NTFS.]

Kopiert eine vorhandene Datei als transaktionierten Vorgang in eine neue Datei, wobei die Anwendung über eine Rückruffunktion über den Fortschritt benachrichtigt wird.

Syntax

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
);

Parameter

[in] lpExistingFileName

Der Name einer vorhandenen Datei.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um diesen Grenzwert auf 32.767 Breitzeichen zu erweitern, stellen Sie dem Pfad "\\?\" voran. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Tipp

Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung aufheben, ohne "\\?\" vorab ausstehen zu müssen. Ausführliche Informationen finden Sie im Abschnitt "Maximale Längenbeschränkung für Pfade" unter Benennen von Dateien, Pfaden und Namespaces.>

Wenn lpExistingFileName nicht vorhanden ist, schlägt die CopyFileTransacted-Funktion fehl, und die GetLastError-Funktion gibt ERROR_FILE_NOT_FOUND zurück.

Die Datei muss sich auf dem lokalen Computer befinden. Andernfalls schlägt die Funktion fehl, und der letzte Fehlercode ist auf ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE festgelegt.

[in] lpNewFileName

Der Name der neuen Datei.

Tipp

[in, optional] lpProgressRoutine

Die Adresse einer Rückruffunktion vom Typ LPPROGRESS_ROUTINE , die jedes Mal aufgerufen wird, wenn ein anderer Teil der Datei kopiert wurde. Dieser Parameter kann NULL sein. Weitere Informationen zur Statusrückruffunktion finden Sie in der CopyProgressRoutine-Funktion .

[in, optional] lpData

Das Argument, das an die Rückruffunktion übergeben werden soll. Dieser Parameter kann NULL sein.

[in, optional] pbCancel

Wenn dieses Flag während des Kopiervorgangs auf TRUE festgelegt ist, wird der Vorgang abgebrochen. Andernfalls wird der Kopiervorgang weiterhin abgeschlossen.

[in] dwCopyFlags

Flags, die angeben, wie die Datei kopiert werden soll. Dieser Parameter kann eine Kombination der folgenden Werte sein.

Wert	Bedeutung
COPY_FILE_COPY_SYMLINK 0x00000800	Wenn die Quelldatei ein symbolischer Link ist, ist die Zieldatei auch ein symbolischer Link, der auf dieselbe Datei verweist, auf die der symbolische Quelllink verweist.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	Der Kopiervorgang schlägt sofort fehl, wenn die Zieldatei bereits vorhanden ist.
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	Die Datei wird kopiert, und die ursprüngliche Datei wird für den Schreibzugriff geöffnet.
COPY_FILE_RESTARTABLE 0x00000002	Der Status der Kopie wird in der Zieldatei nachverfolgt, falls die Kopie fehlschlägt. Die fehlerhafte Kopie kann zu einem späteren Zeitpunkt neu gestartet werden, indem die gleichen Werte für lpExistingFileName und lpNewFileName angegeben werden, die beim fehlgeschlagenen Aufruf verwendet wurden. Dies kann den Kopiervorgang erheblich verlangsamen, da die neue Datei während des Kopiervorgangs möglicherweise mehrmals geleert wird.

[in] hTransaction

Ein Handle für die Transaktion. Dieses Handle wird von der CreateTransaction-Funktion zurückgegeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Wenn lpProgressRoutinePROGRESS_CANCEL zurückgibt, weil der Benutzer den Vorgang abgebrochen hat, gibt CopyFileTransacted null zurück, und GetLastError gibt ERROR_REQUEST_ABORTED zurück. In diesem Fall wird die teilweise kopierte Zieldatei gelöscht.

Wenn lpProgressRoutinePROGRESS_STOP zurückgibt, weil der Benutzer den Vorgang beendet hat, gibt CopyFileTransacted null und GetLastErrorERROR_REQUEST_ABORTED zurück. In diesem Fall bleibt die teilweise kopierte Zieldatei intakt.

Wenn Sie versuchen, diese Funktion mit einem Handle für eine Transaktion aufzurufen, die bereits zurückgesetzt wurde, gibt CopyFileTransacted entweder ERROR_TRANSACTION_NOT_ACTIVE oder ERROR_INVALID_TRANSACTION zurück.

Bemerkungen

Diese Funktion behält erweiterte Attribute, strukturierte OLE-Speicher, alternative NTFS-Dateisystemdatenströme, Sicherheitsattribute und Dateiattribute bei.

Windows 7, Windows Server 2008 R2, Windows Server 2008 und Windows Vista: Sicherheitsressourcenattribute (ATTRIBUTE_SECURITY_INFORMATION) für die vorhandene Datei werden erst in die neue Datei kopiert, bis Windows 8 und Windows Server 2012.

Diese Funktion schlägt mit ERROR_ACCESS_DENIED fehl, wenn die Zieldatei bereits vorhanden ist und das attribut FILE_ATTRIBUTE_HIDDEN oder FILE_ATTRIBUTE_READONLY festgelegt ist.

Verschlüsselte Dateien werden von TxF nicht unterstützt.

Wenn COPY_FILE_COPY_SYMLINK angegeben ist, gelten die folgenden Regeln:

Wenn es sich bei der Quelldatei um einen symbolischen Link handelt, wird der symbolische Link kopiert, nicht die Zieldatei.
Wenn die Quelldatei keine symbolische Verknüpfung ist, gibt es keine Verhaltensänderung.
Wenn die Zieldatei ein vorhandener symbolischer Link ist, wird der symbolische Link überschrieben, nicht die Zieldatei.
Wenn auch COPY_FILE_FAIL_IF_EXISTS angegeben ist und die Zieldatei ein vorhandener symbolischer Link ist, schlägt der Vorgang in allen Fällen fehl.

Wenn COPY_FILE_COPY_SYMLINK nicht angegeben ist, gelten die folgenden Regeln:

Wenn auch COPY_FILE_FAIL_IF_EXISTS angegeben ist und die Zieldatei eine vorhandene symbolische Verknüpfung ist, schlägt der Vorgang nur fehl, wenn das Ziel der symbolischen Verknüpfung vorhanden ist.
Wenn COPY_FILE_FAIL_IF_EXISTS nicht angegeben ist, gibt es keine Verhaltensänderung.

Die Linknachverfolgung wird von TxF nicht unterstützt.

In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Unterstützt
Server Message Block (SMB) 3.0-Protokoll	Nein
SMB 3.0 Transparent Failover (TFO)	Nein
SMB 3.0 mit Dateifreigaben für horizontales Skalieren (SO)	Nein
Freigegebenes Clustervolume-Dateisystem (CsvFS)	Nein
Robustes Dateisystem (Resilient File System, ReFS)	Nein

Beachten Sie, dass SMB 3.0 TxF nicht unterstützt.

Hinweis

Der winbase.h-Header definiert CopyFileTransacted als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll