Funzione CopyFileTransactedA (winbase.h)

Articolo
06/02/2023

[Microsoft consiglia vivamente agli sviluppatori di usare mezzi alternativi per soddisfare le esigenze dell'applicazione. Molti scenari per cui è stato sviluppato TxF possono essere ottenuti tramite tecniche più semplici e più facilmente disponibili. Inoltre, TxF potrebbe non essere disponibile nelle versioni future di Microsoft Windows. Per altre informazioni e alternative a TxF, vedere Alternative all'uso di NTFS transazionale.

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

Sintassi

BOOL CopyFileTransactedA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags,
  [in]           HANDLE             hTransaction
);

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.

Suggerimento

A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente a rimuovere la limitazione MAX_PATH senza anteporre "\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di Denominazione di file, percorsi e spazi dei nomi.>

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

Il file deve risiedere nel computer locale; in caso contrario, la funzione ha esito negativo e l'ultimo codice di errore è impostato su ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] lpNewFileName

Nome del nuovo file.

Suggerimento

[in, optional] lpProgressRoutine

Indirizzo di una funzione di callback di tipo LPPROGRESS_ROUTINE che viene chiamata 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_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.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	L'operazione di copia ha esito negativo immediatamente se il file di destinazione esiste già.
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.

[in] hTransaction

Handle per la transazione. Questo handle viene restituito dalla funzione CreateTransaction .

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, CopyFileTransacted 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, CopyFileTransacted restituirà zero e GetLastError restituirà ERROR_REQUEST_ABORTED. In questo caso, il file di destinazione parzialmente copiato rimane intatto.

Se si tenta di chiamare questa funzione con un handle a una transazione di cui è già stato eseguito il rollback, CopyFileTransacted restituirà ERROR_TRANSACTION_NOT_ACTIVE o ERROR_INVALID_TRANSACTION.

Commenti

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

Windows 7, Windows Server 2008 R2, Windows Server 2008 e Windows Vista: 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.

Questa funzione ha esito negativo con ERROR_ACCESS_DENIED se il file di destinazione esiste già e ha il set di attributi FILE_ATTRIBUTE_HIDDEN o FILE_ATTRIBUTE_READONLY .

I file crittografati non sono supportati da TxF.

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 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 avrà esito negativo solo se la destinazione del collegamento simbolico esiste.
Se non viene specificato COPY_FILE_FAIL_IF_EXISTS , non viene apportata alcuna modifica al comportamento.

Il rilevamento dei collegamenti non è supportato da TxF.

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

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

Si noti che SMB 3.0 non supporta TxF.

Nota

L'intestazione winbase.h definisce CopyFileTransacted 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll