CopyFileW-Funktion (winbase.h)

Artikel
03/06/2024

Kopiert eine vorhandene Datei in eine neue Datei.

Die CopyFileEx-Funktion bietet zwei zusätzliche Funktionen. CopyFileEx kann bei jedem Abschluss eines Teils des Kopiervorgangs eine angegebene Rückruffunktion aufrufen, und CopyFileEx kann während des Kopiervorgangs abgebrochen werden.

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

Syntax

BOOL CopyFileW(
  [in] LPCWSTR lpExistingFileName,
  [in] LPCWSTR lpNewFileName,
  [in] BOOL    bFailIfExists
);

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

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, verfügt eine kopie, die durch einen Aufruf von CopyFile erstellt wurde, auch über das attribut FILE_ATTRIBUTE_READONLY file. 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 attribut FILE_ATTRIBUTE_HIDDEN oder FILE_ATTRIBUTE_READONLY 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.

Hinweis

Der winbase.h-Header definiert CopyFile 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