CopyFileExA-Funktion (winbase.h)
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.
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 .
[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.
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 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 |