Funzione CopyFileExW (winbase.h)

Articolo
06/02/2023

Copia un file esistente in un nuovo file, notificando all'applicazione lo stato di avanzamento tramite una funzione di callback.

Per eseguire questa operazione come operazione transazionata, usare la funzione CopyFileTransacted .

Sintassi

BOOL CopyFileExW(
  [in]           LPCWSTR            lpExistingFileName,
  [in]           LPCWSTR            lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags
);

Parametri

[in] lpExistingFileName

Nome di un file esistente.

Per impostazione predefinita, il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, prependo "\\?\" al percorso. Per altre informazioni, vedere Denominazione di file, percorsi e spazi dei nomi.

Suggerimento

A partire da Windows 10, versione 1607, è possibile scegliere di rimuovere la limitazione MAX_PATH senza pre sospeso "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima lunghezza percorso" di nomi, nomi, percorsi e spazi dei nomi .

Se lpExistingFileName non esiste, la funzione CopyFileEx ha esito negativo e la funzione GetLastError restituisce ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

Nome del nuovo file.

Suggerimento

[in, optional] lpProgressRoutine

Indirizzo di una funzione di callback di tipo LPPROGRESS_ROUTINE chiamata ogni volta che è stata copiata un'altra parte del file. Questo parametro può essere NULL. Per altre informazioni sulla funzione di callback dello stato, vedere la funzione CopyProgressRoutine .

[in, optional] lpData

Argomento da passare alla funzione callback. Questo parametro può essere NULL.

[in, optional] pbCancel

Se questo flag è impostato su TRUE durante l'operazione di copia, l'operazione viene annullata. In caso contrario, l'operazione di copia continuerà a essere completata.

[in] dwCopyFlags

Flag che specificano la modalità di copia del file. Questo parametro può essere una combinazione dei valori seguenti.

Valore	Significato
COPY_FILE_ALLOW_DECRYPTED_DESTINATION 0x00000008	Un tentativo di copia di un file crittografato avrà esito positivo anche se la copia di destinazione non può essere crittografata.
COPY_FILE_COPY_SYMLINK 0x00000800	Se il file di origine è un collegamento simbolico, il file di destinazione è anche un collegamento simbolico che punta allo stesso file a cui punta il collegamento simbolico di origine. Windows Server 2003 e Windows XP: Questo valore non è supportato.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	L'operazione di copia ha esito negativo immediatamente se il file di destinazione esiste già.
COPY_FILE_NO_BUFFERING 0x00001000	L'operazione di copia viene eseguita usando I/O non memorizzati, ignorando le risorse della cache di I/O del sistema. Consigliato per i trasferimenti di file molto grandi. Windows Server 2003 e Windows XP: Questo valore non è supportato.
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	Il file viene copiato e il file originale viene aperto per l'accesso in scrittura.
COPY_FILE_RESTARTABLE 0x00000002	Lo stato di avanzamento della copia viene rilevato nel file di destinazione nel caso in cui la copia non riesca. La copia non riuscita può essere riavviata in un secondo momento specificando gli stessi valori per lpExistingFileName e lpNewFileName come quelli usati nella chiamata non riuscita. Ciò può rallentare significativamente l'operazione di copia perché il nuovo file può essere scaricato più volte durante l'operazione di copia.
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC 0x10000000	Richiedere al canale di trasferimento sottostante comprimere i dati durante l'operazione di copia. La richiesta potrebbe non essere supportata per tutti i supporti, nel qual caso viene ignorata. Gli attributi e i parametri di compressione (complessità computazionale, utilizzo della memoria) non sono configurabili tramite questa API e sono soggetti a modifiche tra versioni del sistema operativo diverse. Questo flag è stato introdotto in Windows 10, versione 1903 e Windows Server 2022. In Windows 10 il flag è supportato per i file che risiedono nelle condivisioni SMB, in cui la versione del protocollo SMB negoziata è SMB v3.1.1 o successiva.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni sull'errore estese, chiamare GetLastError.

Se lpProgressRoutine restituisce PROGRESS_CANCEL a causa dell'annullamento dell'operazione, CopyFileEx restituirà zero e GetLastError restituirà ERROR_REQUEST_ABORTED. In questo caso, il file di destinazione parzialmente copiato viene eliminato.

Se lpProgressRoutine restituisce PROGRESS_STOP a causa dell'arresto dell'operazione, CopyFileEx restituirà zero e GetLastError restituirà ERROR_REQUEST_ABORTED. In questo caso, il file di destinazione parzialmente copiato rimane intatto.

Commenti

Questa funzione mantiene gli attributi estesi, l'archiviazione strutturata OLE, i flussi di file system NTFS alternativi, gli attributi delle risorse di sicurezza e gli attributi dei file.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Gli attributi delle risorse di sicurezza (ATTRIBUTE_SECURITY_INFORMATION) per il file esistente non vengono copiati nel nuovo file fino a Windows 8 e Windows Server 2012.

Le proprietà delle risorse di sicurezza (ATTRIBUTE_SECURITY_INFORMATION) per il file esistente vengono copiate nel nuovo file.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Le proprietà delle risorse di sicurezza per il file esistente non vengono copiate nel nuovo file fino a Windows 8 e Windows Server 2012.

Questa funzione ha esito negativo con ERROR_ACCESS_DENIED se il file di destinazione esiste già e ha il FILE_ATTRIBUTE_HIDDENo FILE_ATTRIBUTE_READONLY attributo impostato.

Quando i file crittografati vengono copiati usando CopyFileEx, la funzione tenta di crittografare il file di destinazione con le chiavi usate nella crittografia del file di origine. Se non è possibile eseguire questa operazione, questa funzione tenta di crittografare il file di destinazione con chiavi predefinite. Se non è possibile eseguire entrambi questi metodi, CopyFileEx non riesce con un codice di errore ERROR_ENCRYPTION_FAILED . Se si vuole che CopyFileEx completi l'operazione di copia anche se il file di destinazione non può essere crittografato, includere il COPY_FILE_ALLOW_DECRYPTED_DESTINATION come valore del parametro dwCopyFlags nella chiamata a CopyFileEx.

Se viene specificato COPY_FILE_COPY_SYMLINK , si applicano le regole seguenti:

Se il file di origine è un collegamento simbolico, il collegamento simbolico viene copiato, non il file di destinazione.
Se il file di origine non è un collegamento simbolico, non esiste alcuna modifica nel comportamento.
Se il file di destinazione è un collegamento simbolico esistente, il collegamento simbolico viene sovrascritto, non il file di destinazione.
Se COPY_FILE_FAIL_IF_EXISTS viene specificato anche e il file di destinazione è un collegamento simbolico esistente, l'operazione ha esito negativo in tutti i casi.

Se COPY_FILE_COPY_SYMLINK non è specificato, si applicano le regole seguenti:

Se COPY_FILE_FAIL_IF_EXISTS viene specificato anche e il file di destinazione è un collegamento simbolico esistente, l'operazione ha esito negativo solo se la destinazione del collegamento simbolico esiste.
Se COPY_FILE_FAIL_IF_EXISTS non è specificato, non esiste alcuna modifica nel comportamento.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Se si scrive un'applicazione che ottimizza le operazioni di copia file in una LAN, è consigliabile usare la funzione TransmitFile da Windows Sockets (Winsock). TransmitFile supporta i trasferimenti di rete ad alte prestazioni e fornisce un'interfaccia semplice per inviare il contenuto di un file a un computer remoto. Per usare TransmitFile, è necessario scrivere un'applicazione client Winsock che invia il file dal computer di origine e un'applicazione server Winsock che usa altre funzioni Winsock per ricevere il file nel computer remoto.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	Sì
Failover trasparente SMB 3.0 (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
File system del volume condiviso del cluster (CsvFS)	Sì
File system resiliente (ReFS)	Sì

Nota

L'intestazione winbase.h definisce CopyFileEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll