Funzione MoveFileTransactedA (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.

Sposta un file esistente o una directory, inclusi i relativi elementi figlio, come operazione transazionata.

Sintassi

BOOL MoveFileTransactedA(
  [in]           LPCSTR             lpExistingFileName,
  [in, optional] LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in]           DWORD              dwFlags,
  [in]           HANDLE             hTransaction
);

Parametri

[in] lpExistingFileName

Nome corrente del file o della directory esistente nel computer locale.

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 .

[in, optional] lpNewFileName

Nuovo nome per il file o la directory. Il nuovo nome non deve esistere già. Un nuovo file può trovarsi in un file system o in un'unità diversa. Una nuova directory deve trovarsi nella stessa unità.

Suggerimento

[in, optional] lpProgressRoutine

Puntatore a una funzione di callback CopyProgressRoutine chiamata ogni volta che è stata spostata un'altra parte del file. La funzione di callback può essere utile se si fornisce un'interfaccia utente che visualizza lo stato di avanzamento dell'operazione. Questo parametro può essere NULL.

[in, optional] lpData

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

[in] dwFlags

Opzioni di spostamento. Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
MOVEFILE_COPY_ALLOWED 2 (0x2)	Se il file deve essere spostato in un volume diverso, la funzione simula lo spostamento usando le funzioni CopyFile e DeleteFile . Se il file viene copiato correttamente in un volume diverso e il file originale non può essere eliminato, la funzione riesce a lasciare intatto il file di origine. Questo valore non può essere usato con MOVEFILE_DELAY_UNTIL_REBOOT.
MOVEFILE_CREATE_HARDLINK 16 (0x10)	Riservato per utilizzi futuri.
MOVEFILE_DELAY_UNTIL_REBOOT 4 (0x4)	Il sistema non sposta il file fino al riavvio del sistema operativo. Il sistema sposta il file immediatamente dopo l'esecuzione di AUTOCHK, ma prima di creare eventuali file di paging. Di conseguenza, questo parametro consente alla funzione di eliminare i file di paging dalle startup precedenti. Questo valore può essere usato solo se il processo si trova nel contesto di un utente appartenente al gruppo administrators o all'account LocalSystem. Questo valore non può essere usato con MOVEFILE_COPY_ALLOWED. L'operazione di scrittura nel valore del Registro di sistema, come descritto in dettaglio nella sezione Osservazioni, è ciò che viene transazionato. Lo spostamento del file viene completato al riavvio del computer, al termine della transazione.
MOVEFILE_REPLACE_EXISTING 1 (0x1)	Se esiste un file denominato lpNewFileName , la funzione sostituisce il relativo contenuto con il contenuto del file lpExistingFileName . Questo valore non può essere utilizzato se lpNewFileName o lpExistingFileName assegna un nome a una directory.
MOVEFILE_WRITE_THROUGH 8 (0x8)	Una chiamata a MoveFileTransacted indica che l'operazione di spostamento del file viene completata al termine dell'operazione di commit. Questo flag non è necessario; non vi sono effetti negativi se questo flag viene specificato, diverso da un rallentamento dell'operazione. La funzione non restituisce finché il file non è stato effettivamente spostato sul disco. L'impostazione di questo valore garantisce che uno spostamento eseguito come operazione di copia ed eliminazione venga scaricato su disco prima che la funzione restituisca. Lo scaricamento si verifica alla fine dell'operazione di copia. Questo valore non ha alcun effetto se MOVEFILE_DELAY_UNTIL_REBOOT è impostato.

[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 informazioni dettagliate sull'errore, chiamare GetLastError.

Quando si sposta un file tra volumi, se lpProgressRoutine restituisce PROGRESS_CANCEL a causa dell'annullamento dell'operazione, MoveFileTransacted restituirà zero e GetLastError restituirà ERROR_REQUEST_ABORTED. Il file esistente rimane intatto.

Quando si sposta un file tra volumi, se lpProgressRoutine restituisce PROGRESS_STOP a causa dell'arresto dell'operazione, MoveFileTransacted restituirà zero e GetLastError restituirà ERROR_REQUEST_ABORTED. Il file esistente rimane intatto.

Commenti

Se il parametro dwFlags specifica MOVEFILE_DELAY_UNTIL_REBOOT, MoveFileTransacted ha esito negativo se non riesce ad accedere al Registro di sistema. La funzione archivia in modo transazionale i percorsi dei file da rinominare al riavvio nel valore del Registro di sistema seguente: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations

Questo valore del Registro di sistema è di tipo REG_MULTI_SZ. Ogni operazione di ridenominazione archivia una delle stringhe con terminazione NULL seguenti, a seconda che la ridenominazione sia un'eliminazione o meno:

szDstFile\0\0

szSrcFile\0szDstFile\0

La stringa szDstFile\0\0 indica che il file szDstFile deve essere eliminato al riavvio.

La stringa szSrcFile\0szDstFile\0 indica che szSrcFile deve essere rinominato szDstFile al riavvio.

Nota Anche se \0\0 non è tecnicamente consentito in un nodo REG_MULTI_SZ , può perché il file viene considerato rinominato in un nome Null.

Il sistema usa queste voci del Registro di sistema per completare le operazioni al riavvio nello stesso ordine in cui sono state emesse. Per altre informazioni sull'uso del flag di MOVEFILE_DELAY_UNTIL_REBOOT , vedere MoveFileWithProgress.

Se un file viene spostato tra volumi, MoveFileTransacted non sposta il descrittore di sicurezza con il file. Al file viene assegnato il descrittore di sicurezza predefinito nella directory di destinazione.

Questa funzione ha sempre esito negativo se si specifica il flag MOVEFILE_FAIL_IF_NOT_TRACKABLE ; il rilevamento 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

SMB 3.0 non supporta TxF.

Requisiti

Requisito	Valore
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

Vedere anche

CopyFileTransacted

Funzioni di gestione file

MoveFileWithProgress

NTFS transazionale

Condividi tramite