CopyFileExA-Funktion (winbase.h)

Kopiert eine vorhandene Datei in eine neue Datei, und benachrichtigt die Anwendung über eine Rückruffunktion über den Fortschritt.

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

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 breite Zeichen zu erweitern, stellen Sie "\\?\" dem Pfad voran. Weitere Informationen finden Sie unter Namensdateien, Pfade und Namespaces.

Wenn lpExistingFileName nicht vorhanden ist, schlägt die CopyFileEx--Funktion fehl, und die GetLastError--Funktion gibt ERROR_FILE_NOT_FOUNDzurü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 breite Zeichen zu erweitern, stellen Sie "\\?\" dem Pfad voran. Weitere Informationen finden Sie unter Namensdateien, Pfade 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 funktion CopyProgressRoutine.

[in, optional] lpData

Das Argument, das an die Rückruffunktion übergeben werden soll. Dieser Parameter kann NULL-sein.

[in, optional] pbCancel

Wenn dieses Kennzeichen 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. Dieser Parameter kann eine Kombination aus den folgenden Werten sein.

Rückgabewert

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

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Um erweiterte Fehlerinformationen abzurufen, rufen Sie GetLastErrorauf.

Wenn lpProgressRoutine aufgrund des Abbruchs des Vorgangs vom Benutzer PROGRESS_CANCEL zurückgibt, gibt CopyFileEx Null zurück, und GetLastError- wird ERROR_REQUEST_ABORTEDzurückgegeben. In diesem Fall wird die teilweise kopierte Zieldatei gelöscht.

Wenn lpProgressRoutine aufgrund des Beendens des Vorgangs PROGRESS_STOP zurückgibt, gibt CopyFileEx Null zurück, und GetLastError- wird ERROR_REQUEST_ABORTEDzurückgegeben. In diesem Fall bleibt die teilweise kopierte Zieldatei erhalten.

Bemerkungen

Diese Funktion behält erweiterte Attribute, OLE-strukturierten Speicher, NTFS-Dateisystem alternative Datenströ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 nach Windows 8 und Windows Server 2012 in die neue Datei kopiert.

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.

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 verschlüsselte Dateien mit CopyFileExkopiert werden, versucht die Funktion, 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 beide Methoden nicht ausgeführt werden können, schlägt CopyFileEx- mit einem ERROR_ENCRYPTION_FAILED Fehlercode fehl. Wenn Sie möchten, dass CopyFileEx den Kopiervorgang abschließen soll, auch wenn die Zieldatei nicht verschlüsselt werden kann, schließen Sie die COPY_FILE_ALLOW_DECRYPTED_DESTINATION als Wert des dwCopyFlags Parameter in Ihren Aufruf von CopyFileExein.

Wenn COPY_FILE_COPY_SYMLINK angegeben ist, gelten die folgenden Regeln:

• Wenn es sich bei der Quelldatei um eine symbolische Verknüpfung handelt, wird die symbolische Verknüpfung kopiert, nicht die Zieldatei.
• Wenn die Quelldatei kein symbolischer Link ist, gibt es keine Verhaltensänderung.
• Wenn es sich bei der Zieldatei um eine vorhandene symbolische Verknüpfung handelt, wird die symbolische Verknüpfung überschrieben, nicht die Zieldatei.
• Wenn COPY_FILE_FAIL_IF_EXISTS ebenfalls angegeben ist und die Zieldatei eine vorhandene symbolische Verknüpfung ist, schlägt der Vorgang in allen Fällen fehl.

• Wenn COPY_FILE_FAIL_IF_EXISTS ebenfalls 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 Dateikopievorgänge über ein LAN optimiert, sollten Sie die TransmitFile-Funktion aus 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-zu verwenden, müssen Sie eine Winsock-Clientanwendung schreiben, die die Datei vom Quellcomputer sendet, sowie eine Winsock-Serveranwendung, die andere Winsock-Funktionen verwendet, um die Datei auf dem Remotecomputer zu empfangen.

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

Anforderungen

Siehe auch

CopyFile-

CopyFileTransacted-

CopyProgressRoutine-

CreateFile-

Dateiattributekonstanten

Dateiverwaltungsfunktionen

MoveFile-

MoveFileWithProgress-

symbolische Verknüpfungen

TransmitFile-