Freigeben über


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.

Tipp Ab Windows 10 Version 1607 können Sie die MAX_PATH Zeichenbeschränkung entfernen, ohne "\\?\". Weitere Informationen finden Sie im Abschnitt "Maximale Pfadbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .
 
Wenn lpExistingFileName nicht vorhanden ist, schlägt die CopyFile2-Funktion fehl 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.

Tipp Ab Windows 10 Version 1607 können Sie die MAX_PATH Zeichenbeschränkung entfernen, ohne "\\?\". Weitere Informationen finden Sie im Abschnitt "Maximale Pfadbegrenzung" unter Benennung 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
S_OK
Der Kopiervorgang wurde erfolgreich abgeschlossen.
HRESULT_FROM_WIN32(ERROR_REQUEST_PAUSED)
Der Kopiervorgang wurde von einer COPYFILE2_PROGRESS_PAUSE von der Rückruffunktion CopyFile2ProgressRoutine angehalten.
HRESULT_FROM_WIN32(ERROR_REQUEST_ABORTED)
Der Kopiervorgang wurde durch einen COPYFILE2_PROGRESS_CANCEL oder COPYFILE2_PROGRESS_STOP von der Rückruffunktion CopyFile2ProgressRoutine angehalten.
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)
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.
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)
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

Siehe auch

COPYFILE2_EXTENDED_PARAMETERS

Dateiverwaltungsfunktionen