Funzione MoveFileWithProgressA (winbase.h)

Articolo
03/03/2024

Sposta un file o una directory, inclusi i relativi elementi figlio. È possibile fornire una funzione di callback che riceve notifiche di stato.

Per eseguire questa operazione come operazione transazionata, usare la funzione MoveFileTransacted .

Sintassi

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

Parametri

[in] lpExistingFileName

Nome del file o della directory esistente nel computer locale.

Se dwFlags specifica MOVEFILE_DELAY_UNTIL_REBOOT, il file non può esistere in una condivisione remota perché le operazioni ritardate vengono eseguite prima che la rete sia disponibile.

Per impostazione predefinita, il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, prependo "\\?\" al percorso. Per altre informazioni, vedere Denominazione di file, percorsi e spazi dei nomi.

Suggerimento

A partire da Windows 10, versione 1607, è possibile scegliere di rimuovere la limitazione MAX_PATH senza pre sospeso "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima lunghezza percorso" di nomi, nomi, percorsi e spazi dei nomi .

[in, optional] lpNewFileName

Nuovo nome del file o della directory nel computer locale.

Quando si sposta un file, lpNewFileName può trovarsi in un file system o in un volume diverso. Se lpNewFileName è in un'altra unità, è necessario impostare il flag di MOVEFILE_COPY_ALLOWED in dwFlags.

Quando si sposta una directory, lpExistingFileName e lpNewFileName devono trovarsi nella stessa unità.

Se dwFlags specifica MOVEFILE_DELAY_UNTIL_REBOOT e lpNewFileName è NULL, MoveFileWithProgress registra lpExistingFileName da eliminare al riavvio del sistema. La funzione ha esito negativo se non riesce ad accedere al Registro di sistema per archiviare le informazioni sull'operazione di eliminazione. Se lpExistingFileName fa riferimento a una directory, il sistema rimuove la directory al riavvio solo se la directory è vuota.

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 finché il sistema operativo non viene riavviato. Il sistema sposta il file immediatamente dopo l'esecuzione di AUTOCHK, ma prima di creare file di paging. Di conseguenza, questo parametro consente alla funzione di eliminare i file di paging dalle avvio precedenti. Questo valore può essere usato solo se il processo si trova nel contesto di un utente che appartiene al gruppo di amministratori o all'account LocalSystem. Questo valore non può essere usato con MOVEFILE_COPY_ALLOWED.
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 (0x20)	La funzione ha esito negativo se il file di origine è un'origine di collegamento, ma non è possibile tenere traccia del file dopo lo spostamento. Questa situazione può verificarsi se la destinazione è un volume formattato con il file system FAT.
MOVEFILE_REPLACE_EXISTING 1 (0x1)	Se esiste un file denominato lpNewFileName , la funzione sostituisce il contenuto del file lpExistingFileName . Questo valore non può essere usato se lpNewFileName o lpExistingFileName assegna un nome a una directory.
MOVEFILE_WRITE_THROUGH 8 (0x8)	La funzione non restituisce fino a quando 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 scaricata 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.

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, MoveFileWithProgress restituirà zero e GetLastError restituirà ERROR_REQUEST_ABORTED. Il file esistente è rimasto intatto.

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

Commenti

La funzione MoveFileWithProgress coordina l'operazione con il servizio di rilevamento dei collegamenti, in modo che le origini di collegamento possano essere rilevate man mano che vengono spostate.

Per eliminare o rinominare un file, è necessario disporre dell'autorizzazione di eliminazione per il file o eliminare l'autorizzazione figlio nella directory padre. Se si configura una directory con tutti gli accessi, ad eccezione dell'eliminazione e dell'eliminazione figlio e degli elenchi di controllo di accesso dei nuovi file, è necessario poter creare un file senza poter eliminarlo. Tuttavia, è possibile creare un file e si otterrà tutto l'accesso richiesto nell'handle restituito al momento della creazione del file. Se è stata richiesta l'autorizzazione di eliminazione al momento della creazione del file, è possibile eliminare o rinominare il file con tale handle, ma non con altri.

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

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

CsvFs eseguirà il reindirizzamento di I/O per i file compressi.

Nota

L'intestazione winbase.h definisce MoveFileWithProgress come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante 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

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