CopyFileExA-Funktion (winbase.h)

Artikel
06/02/2023

Kopiert eine vorhandene Datei in eine neue Datei und benachrichtigt die Anwendung anhand einer Rückruffunktion über den Verlauf.

Um diesen Vorgang als transaktionierten Vorgang auszuführen, verwenden Sie die CopyFileTransacted-Funktion .

Syntax

BOOL CopyFileExA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags
);

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 CopyFileEx-Funktion fehl, und die GetLastError-Funktion gibt ERROR_FILE_NOT_FOUND zurück.

[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. Für diesen Parameter ist eine Kombination der folgenden Werte gültig.

Wert	Bedeutung
COPY_FILE_ALLOW_DECRYPTED_DESTINATION 0x00000008	Ein Versuch, eine verschlüsselte Datei zu kopieren, ist auch dann erfolgreich, wenn die Zielkopie nicht verschlüsselt werden kann.
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. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	Der Kopiervorgang schlägt sofort fehl, wenn die Zieldatei bereits vorhanden ist.
COPY_FILE_NO_BUFFERING 0x00001000	Der Kopiervorgang wird mit nicht gepufferten E/A-Vorgängen ausgeführt, wobei die System-E/A-Cacheressourcen umgangen werden. Empfohlen für sehr große Dateiübertragungen. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
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.
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC 0x10000000	Fordern Sie den zugrunde liegenden Übertragungskanal an, die Daten während des Kopiervorgangs zu komprimieren. Die Anforderung wird möglicherweise nicht für alle Medien unterstützt, in diesem Fall wird sie ignoriert. Die Komprimierungsattribute und -parameter (Rechenkomplexität, Speicherauslastung) können nicht über diese API konfiguriert werden und können zwischen verschiedenen Betriebssystemversionen geändert werden. Dieses Flag wurde in Windows 10 Version 1903 und Windows Server 2022 eingeführt. Auf Windows 10 wird das Flag für Dateien unterstützt, die sich auf SMB-Freigaben befinden, wobei die ausgehandelte SMB-Protokollversion SMB v3.1.1 oder höher ist.

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 CopyFileEx null und GetLastErrorERROR_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 CopyFileEx null und GetLastErrorERROR_REQUEST_ABORTED zurück. In diesem Fall bleibt die teilweise kopierte Zieldatei intakt.

Hinweise

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

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

Die Sicherheitsressourceneigenschaften (ATTRIBUTE_SECURITY_INFORMATION) für die vorhandene Datei werden in die neue Datei kopiert.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Sicherheitsressourceneigenschaften 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.

Wenn verschlüsselte Dateien mit CopyFileEx kopiert werden, versucht die Funktion, die Zieldatei mit den Schlüsseln zu verschlüsseln, die bei der Verschlüsselung der Quelldatei verwendet werden. Wenn dies nicht möglich ist, versucht diese Funktion, die Zieldatei mit Standardschlüsseln zu verschlüsseln. Wenn beide Methoden nicht ausgeführt werden können, schlägt CopyFileEx mit einem ERROR_ENCRYPTION_FAILED Fehlercode fehl. Wenn CopyFileEx den Kopiervorgang auch dann abschließen soll, wenn die Zieldatei nicht verschlüsselt werden kann, schließen Sie den COPY_FILE_ALLOW_DECRYPTED_DESTINATION als Wert des dwCopyFlags-Parameters in Ihren Aufruf von CopyFileEx ein.

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 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.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Wenn Sie eine Anwendung schreiben, die Dateikopiervorgänge über ein LAN optimiert, sollten Sie die TransmitFile-Funktion von Windows Sockets (Winsock) verwenden. TransmitFile unterstützt leistungsstarke Netzwerkübertragungen und bietet eine einfache Schnittstelle zum Senden des Inhalts einer Datei an einen Remotecomputer. Um TransmitFile verwenden zu können, müssen Sie eine Winsock-Clientanwendung schreiben, die die Datei vom Quellcomputer sendet, sowie eine Winsock-Serveranwendung, die andere Winsock-Funktionen zum Empfangen der Datei auf dem Remotecomputer verwendet.

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

Technologie	Unterstützt
SMB 3.0-Protokoll (Server Message Block)	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Hinweis

Der winbase.h-Header definiert CopyFileEx 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
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll