Funzione MoveFileExA (winbase.h)

Articolo
06/27/2024

Sposta un file o una directory esistente, inclusi i relativi elementi figlio, con varie opzioni di spostamento.

La funzione MoveFileWithProgress è equivalente alla funzione MoveFileEx , ad eccezione del fatto che MoveFileWithProgress consente di fornire una funzione di callback che riceve notifiche di stato.

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

Sintassi

BOOL MoveFileExA(
  [in]           LPCSTR lpExistingFileName,
  [in, optional] LPCSTR lpNewFileName,
  [in]           DWORD  dwFlags
);

Parametri

[in] lpExistingFileName

Nome corrente del file o della directory 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, anteporre "\\?\" al percorso. Per altre informazioni, vedere denominazione di file, percorsi e spazi dei nomi.

Mancia

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

[in, optional] lpNewFileName

Nuovo nome del file o della directory nel computer locale.

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

Quando si sposta una directory, la destinazione deve trovarsi nella stessa unità.

Se dwFlags specifica MOVEFILE_DELAY_UNTIL_REBOOT e lpNewFileName è null, MoveFileEx registra il file lpExistingFileName da eliminare al riavvio del sistema. Se lpExistingFileName fa riferimento a una directory, il sistema rimuove la directory al riavvio solo se la directory è vuota.

Mancia

[in] dwFlags

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 ha esito positivo lasciando intatto il file di origine. Questo valore non può essere usato con MOVEFILE_DELAY_UNTIL_REBOOT.
MOVEFILE_CREATE_HARDLINK 16 (0x10)	Riservato per uso futuro.
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 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 che appartiene al gruppo administrators 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 relativo contenuto con il contenuto del file lpExistingFileName, purché siano soddisfatti i requisiti di sicurezza relativi agli elenchi di controllo di accesso (ACL). Per altre informazioni, vedere la sezione Osservazioni di questo argomento. Se lpNewFileName nomi di una directory esistente, viene segnalato un errore.
MOVEFILE_WRITE_THROUGH 8 (0x8)	La funzione non restituisce finché il file non viene 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 venga restituita. 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 (0). Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

Se il parametro dwFlags specifica MOVEFILE_DELAY_UNTIL_REBOOT, MoveFileEx ha esito negativo se non riesce ad accedere al Registro di sistema. La funzione archivia 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:

szSrcFile\0\0
szSrcFile\0szDstFile\0

La stringa szSrcFile\0\0 indica che il file szSrcFile 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ò essere 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. Ad esempio, il frammento di codice seguente crea voci del Registro di sistema che eliminano szSrcFile e rinominano szSrcFile in modo che siano szDstFile al riavvio:

MoveFileEx(szSrcFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);
MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

Poiché le operazioni di spostamento ed eliminazione effettive specificate con il flag MOVEFILE_DELAY_UNTIL_REBOOT vengono eseguite dopo la fine dell'esecuzione dell'applicazione chiamante, il valore restituito non può riflettere l'esito positivo o negativo dello spostamento o dell'eliminazione del file. Riflette invece l'esito positivo o negativo nell'inserimento delle voci appropriate nel Registro di sistema.

Il sistema elimina una directory contrassegnata per l'eliminazione con il flag MOVEFILE_DELAY_UNTIL_REBOOT solo se è vuoto. Per garantire l'eliminazione delle directory, spostare o eliminare tutti i file dalla directory prima di tentare di eliminarli. I file possono trovarsi nella directory in fase di avvio, ma devono essere eliminati o spostati prima che il sistema possa eliminare la directory.

Le operazioni di spostamento ed eliminazione vengono eseguite al momento dell'avvio nello stesso ordine in cui sono specificate nell'applicazione chiamante. Per eliminare una directory in cui sono presenti file in fase di avvio, eliminare prima i file.

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

La funzione MoveFileEx 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 gli ACL dei nuovi file vengono ereditati, sarà possibile creare un file senza poterlo eliminare. Tuttavia, è possibile creare un file e ottenere tutto l'accesso richiesto nell'handle restituito all'utente al momento della creazione del file. Se si richiede l'autorizzazione di eliminazione al momento della creazione del file, è possibile eliminare o rinominare il file con tale handle ma non con qualsiasi altro handle. Per altre informazioni, vedere File Security and Access Rights.

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

Tecnologia	Sostenuto
Protocollo SMB (Server Message Block) 3.0	Sì
SMB 3.0 Transparent Failover (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
Cluster Shared Volume File System (CsvFS)	Sì
Resilient File System (ReFS)	Sì

Esempi

Per un esempio, vedere Creazione e uso di un file temporaneo.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	winbase.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll