Funzione CopyFileExW (winbase.h)

Articolo
11/20/2024

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, anteporre "\\?\" al percorso. Per altre informazioni, vedere denominazione di file, percorsi e spazi dei nomi.

Mancia

A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente alla rimozione della limitazione MAX_PATH senza anteporre "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di 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.

Mancia

[in, optional] lpProgressRoutine

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

[in, optional] lpData

Argomento da passare alla funzione di 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 copiare 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 operazioni di I/O non memorizzate, ignorando le risorse della cache di I/O di sistema. Consigliato per trasferimenti di file di grandi dimensioni. 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 il 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 diverse del sistema operativo. Questo flag è stato introdotto in Windows 10, versione 1903 e Windows Server 2022. In Windows 10 il flag è supportato per i file che risiedono in condivisioni SMB, in cui la versione del protocollo SMB negoziata è SMB v3.1.1 o versione 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 estese sull'errore, 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 da parte dell'utente, CopyFileEx restituirà zero e GetLastError restituirà ERROR_REQUEST_ABORTED. In questo caso, il file di destinazione parzialmente copiato rimane intatto.

Osservazioni

Questa funzione mantiene gli attributi estesi, l'archiviazione strutturata OLE, i flussi di dati alternativi del file system NTFS, 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: 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: 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_HIDDEN o 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 ha esito negativo con un codice di errore ERROR_ENCRYPTION_FAILED. Se si desidera CopyFileEx completare 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 si specifica 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 viene apportata alcuna modifica al comportamento.
Se il file di destinazione è un collegamento simbolico esistente, il collegamento simbolico viene sovrascritto, non il file di destinazione.
Se viene specificato anche COPY_FILE_FAIL_IF_EXISTS e il file di destinazione è un collegamento simbolico esistente, l'operazione ha esito negativo in tutti i casi.

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

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

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Se si sta scrivendo un'applicazione che ottimizza le operazioni di copia dei file in una LAN, è consigliabile usare la funzione TransmitFile da Windows Sockets (Winsock). TransmitFile supporta 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	Sostenuto
Protocollo SMB (Server Message Block) 3.0	Sì
SMB 3.0 Transparent Failover (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
Cluster Shared Volume File System (CsvFS)	Sì
Resilient File System (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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	winbase.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll