CopyFile2-Funktion (winbase.h)
Kopiert eine vorhandene Datei in eine neue Datei und benachrichtigt die Anwendung anhand einer Rückruffunktion über den Verlauf.
Syntax
HRESULT CopyFile2(
[in] PCWSTR pwszExistingFileName,
[in] PCWSTR pwszNewFileName,
[in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);
Parameter
[in] pwszExistingFileName
Der Name einer vorhandenen Datei.
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.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND).
[in] pwszNewFileName
Der Name der neuen Datei.
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.
[in, optional] pExtendedParameters
Optionale Adresse einer COPYFILE2_EXTENDED_PARAMETERS-Struktur .
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt der Rückgabewert TRUE zurück, wenn er an das MAKRO SUCCEEDED übergeben wird.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Der Kopiervorgang wurde erfolgreich abgeschlossen. |
|
Der Kopiervorgang wurde von einer COPYFILE2_PROGRESS_PAUSE von der Rückruffunktion CopyFile2ProgressRoutine angehalten. |
|
Der Kopiervorgang wurde durch einen COPYFILE2_PROGRESS_CANCEL oder COPYFILE2_PROGRESS_STOP von der Rückruffunktion CopyFile2ProgressRoutine angehalten. |
|
Das dwCopyFlags-Element der COPYFILE2_EXTENDED_PARAMETERS-Struktur , die über den pExtendedParameters-Parameterparameters-Parameter übergeben wird, enthält das COPY_FILE_FAIL_IF_EXISTS-Flag , und ein konfliktierender Name ist vorhanden. |
|
Das dwCopyFlags-Element der COPYFILE2_EXTENDED_PARAMETERS-Struktur , die über den pExtendedParameters-Parameterparameters-Parameter übergeben wird, enthält das COPY_FILE_FAIL_IF_EXISTS-Flag , und ein konfliktierender Name ist vorhanden. |
Hinweise
Diese Funktion behält erweiterte Attribute, strukturierte OLE-Speicher, alternative NTFS-Dateisystemdatenströme und Dateiattribute bei. Sicherheitsattribute für die vorhandene Datei werden nicht in die neue Datei kopiert. Verwenden Sie zum Kopieren von Sicherheitsattributen die ShFileOperation-Funktion .
Diese Funktion schlägt mit HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) fehl, wenn die Zieldatei bereits vorhanden ist und das attribut FILE_ATTRIBUTE_HIDDEN oder FILE_ATTRIBUTE_READONLY festgelegt ist.
Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie das _WIN32_WINNT Makro als _WIN32_WINNT_WIN8 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.
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 |
Ab Windows 10, Version 1903 und Windows Server 2022, wird ein neuer Wert, COPY_FILE_REQUEST_COMPRESSED_TRAFFIC, für das dwCopyFlags-Feld der COPYFILE2_EXTENDED_PARAMETERS-Struktur unterstützt, die im pExtendedParameters-Argument an diese Funktion übergeben wird. Dieser neue Wert fordert an, dass der zugrunde liegende Übertragungskanal die Daten während des Kopiervorgangs komprimiert. Die Anforderung wird möglicherweise nicht für alle Medien unterstützt, in diesem Fall wird sie ignoriert. Die Komprimierungsattribute und -parameter (Rechenkomplexität, Arbeitsspeicherauslastung) sind über diese API nicht konfigurierbar und können sich zwischen verschiedenen Betriebssystemversionen ändern. Auf Windows 10 wird das Flag für Dateien unterstützt, die sich auf SMB-Freigaben befinden, wobei die ausgehandelte SMB-Protokollversion SMB v3.1.1 oder höher ist.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 8 [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2012 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winbase.h (einschließlich Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |