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

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

Si noti che SMB 3.0 non supporta TxF.

Requisiti

Vedere anche

CopyProgressRoutine

CreateFileTransacted

Costanti degli attributi di file

Funzioni di gestione file

MoveFileTransacted

Collegamenti simbolici

NTFS transazionale