CopyFileTransactedA-Funktion (winbase.h)

Artikel
11/20/2024

[Microsoft empfiehlt Entwicklern dringend, alternative Mittel zu nutzen, um die Anforderungen Ihrer Anwendung zu erreichen. 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 Transactional NTFS.]

Kopiert eine vorhandene Datei als transacted-Vorgang in eine neue Datei, und benachrichtigt die Anwendung über eine Rückruffunktion über den Fortschritt.

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 breite Zeichen zu erweitern, stellen Sie "\\?\" dem Pfad voran. Weitere Informationen finden Sie unter Namensdateien, Pfade und Namespaces.

Trinkgeld

Ab Windows 10, Version 1607, können Sie sich anmelden, um die MAX_PATH Einschränkung zu entfernen, ohne "\\?\". Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbeschränkung" Benennungsdateien, Pfade und Namespaces.>.

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

Die Datei muss sich auf dem lokalen Computer befinden; andernfalls schlägt die Funktion fehl, und der letzte Fehlercode wird auf ERROR_TRANSACTIONS_UNSUPPORTED_REMOTEfestgelegt.

[in] lpNewFileName

Der Name der neuen Datei.

Trinkgeld

[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 funktion CopyProgressRoutine.

[in, optional] lpData

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

[in, optional] pbCancel

Wenn dieses Kennzeichen 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 aus den folgenden Werten sein.

Wert	Bedeutung
COPY_FILE_COPY_SYMLINK 0x00000800	Wenn es sich bei der Quelldatei um eine symbolische Verknüpfung handelt, ist die Zieldatei auch eine symbolische Verknüpfung, die auf dieselbe Datei verweist, auf die die symbolische Verknüpfung der Quelle 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 Originaldatei wird für schreibgeschützten Zugriff geöffnet.
COPY_FILE_RESTARTABLE 0x00000002	Der Fortschritt der Kopie wird in der Zieldatei nachverfolgt, falls die Kopie fehlschlägt. Die fehlgeschlagene Kopie kann zu einem späteren Zeitpunkt neu gestartet werden, indem sie die gleichen Werte für lpExistingFileName und lpNewFileName als diejenigen angeben, die im fehlgeschlagenen Aufruf verwendet werden. Dies kann den Kopiervorgang erheblich verlangsamen, da die neue Datei während des Kopiervorgangs mehrmals geleert werden kann.

[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 fehlschlägt, ist der Rückgabewert null. Um erweiterte Fehlerinformationen abzurufen, rufen Sie GetLastErrorauf.

Wenn lpProgressRoutine aufgrund des Abbruchs des Vorgangs vom Benutzer PROGRESS_CANCEL zurückgibt, gibt CopyFileTransacted Null zurück, und GetLastError- wird ERROR_REQUEST_ABORTEDzurückgegeben. In diesem Fall wird die teilweise kopierte Zieldatei gelöscht.

Wenn lpProgressRoutine aufgrund des Beendens des Vorgangs PROGRESS_STOP zurückgibt, gibt CopyFileTransacted Null zurück, und GetLastError- wird ERROR_REQUEST_ABORTEDzurückgegeben. In diesem Fall bleibt die teilweise kopierte Zieldatei erhalten.

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_TRANSACTIONzurück.

Bemerkungen

Diese Funktion behält erweiterte Attribute, OLE-strukturierten Speicher, NTFS-Dateisystem alternative Datenströ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 nach Windows 8 und Windows Server 2012 in die neue Datei kopiert.

Diese Funktion schlägt mit ERROR_ACCESS_DENIED fehl, wenn die Zieldatei bereits vorhanden ist und der FILE_ATTRIBUTE_HIDDEN oder FILE_ATTRIBUTE_READONLY Attributsatz 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 eine symbolische Verknüpfung handelt, wird die symbolische Verknüpfung kopiert, nicht die Zieldatei.
Wenn die Quelldatei kein symbolischer Link ist, gibt es keine Verhaltensänderung.
Wenn es sich bei der Zieldatei um eine vorhandene symbolische Verknüpfung handelt, wird die symbolische Verknüpfung überschrieben, nicht die Zieldatei.
Wenn COPY_FILE_FAIL_IF_EXISTS ebenfalls angegeben ist und die Zieldatei eine vorhandene symbolische Verknüpfung ist, schlägt der Vorgang in allen Fällen fehl.

Wenn COPY_FILE_COPY_SYMLINK nicht angegeben ist, gelten die folgenden Regeln:

Wenn COPY_FILE_FAIL_IF_EXISTS ebenfalls 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 Linkverfolgung wird von TxF nicht unterstützt.

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

Technologie	Abgestützt
Server Message Block (SMB) 3.0-Protokoll	Nein
SMB 3.0 Transparent Failover (TFO)	Nein
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Nein
Freigegebenes Clustervolumedateisystem (CsvFS)	Nein
Resilient File System (ReFS)	Nein

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

Anmerkung

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

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll