CopyFileW-Funktion (winbase.h)

Artikel
11/20/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- während des Kopiervorgangs abgebrochen werden kann.

Verwenden Sie die CopyFileTransacted--Funktion, um diesen Vorgang als transacted-Vorgang auszuführen.

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 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 CopyFile- fehl, und GetLastError gibt ERROR_FILE_NOT_FOUNDzurück.

[in] lpNewFileName

Der Name der neuen Datei.

Trinkgeld

[in] bFailIfExists

Wenn dieser Parameter TRUE ist und die durch 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 fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

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

Dateiattribute für die vorhandene Datei werden in die neue Datei kopiert. Wenn beispielsweise eine vorhandene Datei über das FILE_ATTRIBUTE_READONLY Dateiattribut verfügt, weist eine Kopie, die über einen Aufruf von CopyFile- erstellt wurde, auch das FILE_ATTRIBUTE_READONLY-Dateiattribut auf. 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 der FILE_ATTRIBUTE_HIDDEN oder FILE_ATTRIBUTE_READONLY Attributsatz festgelegt ist.

Wenn CopyFile- verwendet wird, um eine verschlüsselte Datei zu kopieren, wird versucht, die Zieldatei mit den Schlüsseln zu verschlüsseln, die in 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 für symbolische Verknüpfungen – Wenn es sich bei der Quelldatei um einen symbolischen Link handelt, ist die tatsächliche kopierte Datei das Ziel der symbolischen Verknüpfung.

Wenn die Zieldatei bereits vorhanden ist und eine symbolische Verknüpfung ist, wird das Ziel der symbolischen Verknüpfung von der Quelldatei überschrieben.

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	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
Resilient File System (ReFS)	Ja

Beispiele

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

Anmerkung

Der winbase.h-Header definiert CopyFile als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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 XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll