CopyFile-Funktion (winbase.h)

Artikel
03/03/2024

Kopiert eine vorhandene Datei in eine neue Datei.

Die CopyFileEx-Funktion bietet zwei zusätzliche Funktionen. CopyFileEx kann eine angegebene Rückruffunktion jedes Mal aufrufen, wenn ein Teil des Kopiervorgangs abgeschlossen ist, und CopyFileEx kann während des Kopiervorgangs abgebrochen werden.

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

Syntax

BOOL CopyFile(
  [in] LPCTSTR lpExistingFileName,
  [in] LPCTSTR lpNewFileName,
  [in] BOOL    bFailIfExists
);

Parameter

[in] lpExistingFileName

Der Name einer vorhandenen Datei.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um dieses Limit auf 32.767 breite Zeichen zu erweitern, müssen Sie dem Pfad "\\?\" voranstellen. 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 entfernen, ohne "\\?\" vorauszustellen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .

Wenn lpExistingFileName nicht vorhanden ist, schlägt CopyFile fehl, und GetLastError gibt ERROR_FILE_NOT_FOUND zurück.

[in] lpNewFileName

Der Name der neuen Datei.

Tipp

[in] bFailIfExists

Wenn dieser Parameter TRUE ist und die von lpNewFileName angegebene neue Datei bereits vorhanden ist, schlägt die Funktion fehl. Wenn dieser Parameter FALSE ist und die neue Datei bereits vorhanden ist, überschreibt die Funktion die vorhandene Datei und ist erfolgreich.

Rückgabewert

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

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

Hinweise

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 Windows 8 und Windows Server 2012 in die neue Datei kopiert.

Dateiattribute für die vorhandene Datei werden in die neue Datei kopiert. Wenn z. B. eine vorhandene Datei über das attribut FILE_ATTRIBUTE_READONLY datei verfügt, wird eine Kopie, die durch einen Aufruf von CopyFile erstellt wurde, auch das attribut FILE_ATTRIBUTE_READONLY datei aufweisen. Weitere Informationen finden Sie unter Abrufen und Ändern von Dateiattributen.

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

Wenn CopyFile zum Kopieren einer verschlüsselten Datei verwendet wird, wird versucht, 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 keine dieser Methoden ausgeführt werden kann, schlägt CopyFile mit einem ERROR_ENCRYPTION_FAILED Fehlercode fehl.

Verhalten symbolischer Verknüpfungen: Wenn es sich bei der Quelldatei um einen symbolischen Link handelt, ist die kopierte Datei das Ziel des symbolischen Links.

Wenn die Zieldatei bereits vorhanden ist und ein symbolischer Link ist, wird das Ziel des symbolischen Links von der Quelldatei überschrieben.

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

Beispiele

Ein Beispiel finden Sie unter Abrufen und Ändern von Dateiattributen.

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 (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll