Funzione CopyFileTransactedA (winbase.h)

[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.

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.

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.

[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.

[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 estese sull'errore, 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.

Osservazioni

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: 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 FILE_ATTRIBUTE_HIDDEN o FILE_ATTRIBUTE_READONLY attributo impostato.

I file crittografati non sono supportati da TxF.

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 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.

Il rilevamento dei collegamenti non è supportato da TxF.

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

Si noti che SMB 3.0 non supporta TxF.

Fabbisogno

Vedere anche

CopyProgressRoutine

CreateFileTransacted

costanti dell'attributo file

funzioni di gestione file

MoveFileTransacted

collegamenti simbolici

NTFS transazionale