Funzione ReplaceFileA (winbase.h)

Articolo
11/20/2024

Sostituisce un file con un altro file, con la possibilità di creare una copia di backup del file originale. Il file di sostituzione presuppone il nome del file sostituito e la relativa identità.

Sintassi

BOOL ReplaceFileA(
  [in]           LPCSTR lpReplacedFileName,
  [in]           LPCSTR lpReplacementFileName,
  [in, optional] LPCSTR lpBackupFileName,
  [in]           DWORD  dwReplaceFlags,
                 LPVOID lpExclude,
                 LPVOID lpReserved
);

Parametri

[in] lpReplacedFileName

Nome del file da sostituire.

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.

Questo file viene aperto con i diritti di accesso GENERIC_READ, DELETEe SYNCHRONIZE. La modalità di condivisione è FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

Il chiamante deve avere accesso in scrittura al file da sostituire. Per altre informazioni, vedere File Security and Access Rights.

[in] lpReplacementFileName

Nome del file che sostituirà il file lpReplacedFileName.

Mancia

La funzione tenta di aprire questo file con il SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETEe i diritti di accesso WRITE_DAC in modo che possa mantenere tutti gli attributi e gli ACL. In caso di esito negativo, la funzione tenta di aprire il file con i diritti di accesso SYNCHRONIZE, GENERIC_READ, DELETEe WRITE_DAC. Non è specificata alcuna modalità di condivisione.

[in, optional] lpBackupFileName

Nome del file che fungerà da copia di backup del file lpReplacedFileName. Se questo parametro è NULL, non viene creato alcun file di backup. Per informazioni dettagliate sull'implementazione del file di backup, vedere la sezione Osservazioni.

Mancia

[in] dwReplaceFlags

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

Valore	Significato
REPLACEFILE_WRITE_THROUGH 0x00000001	Questo valore non è supportato.
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	Ignora gli errori che si verificano durante l'unione di informazioni, ad esempio attributi e ACL, dal file sostituito al file di sostituzione. Pertanto, se si specifica questo flag e non si dispone di accesso WRITE_DAC, la funzione ha esito positivo ma gli elenchi di controllo di accesso non vengono mantenuti.
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	Ignora gli errori che si verificano durante l'unione delle informazioni ACL dal file sostituito al file di sostituzione. Pertanto, se si specifica questo flag e non si dispone di accesso WRITE_DAC, la funzione ha esito positivo ma gli elenchi di controllo di accesso non vengono mantenuti. Per compilare un'applicazione che usa questo valore, definire la macro _WIN32_WINNT come 0x0600 o versione successiva. Windows Server 2003 e Windows XP: Questo valore non è supportato.

lpExclude

Riservato per uso futuro.

lpReserved

Riservato per uso futuro.

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. Di seguito sono riportati i possibili codici di errore per questa funzione.

Codice/valore restituito	Descrizione
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 (0x498)	Impossibile rinominare il file di sostituzione. Se è stato specificato lpBackupFileName, i file sostituiti e sostitutivi mantengono i nomi dei file originali. In caso contrario, il file sostituito non esiste più e il file di sostituzione esiste sotto il nome originale.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 (0x499)	Impossibile spostare il file di sostituzione. Il file sostitutivo esiste ancora sotto il nome originale; Tuttavia, ha ereditato i flussi di file e gli attributi dal file che sta sostituendo. Il file da sostituire esiste ancora con un nome diverso. Se viene specificato lpBackupFileName, sarà il nome del file sostituito.
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 (0x497)	Impossibile eliminare il file sostituito. I file sostituiti e sostitutivi mantengono i nomi di file originali.

Se viene restituito un altro errore, ad esempio ERROR_INVALID_PARAMETER, i file sostituiti e sostitutivi manterranno i nomi di file originali. In questo scenario, un file di backup non esiste e non è garantito che il file di sostituzione abbia ereditato tutti gli attributi e i flussi del file sostituito.

Osservazioni

suggerimento A partire da Windows 10, versione 1607, per la versione Unicode di questa funzione (ReplaceFileW), è possibile acconsentire esplicitamente per rimuovere la limitazione MAX_PATH. Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di nomi, percorsi e spazi dei nomi.

La funzione ReplaceFile combina diversi passaggi all'interno di una singola funzione. Un'applicazione può chiamare ReplaceFile invece di chiamare funzioni separate per salvare i dati in un nuovo file, rinominare il file originale usando un nome temporaneo, rinominare il nuovo file con lo stesso nome del file originale ed eliminare il file originale. Un altro vantaggio è che ReplaceFile non solo copia i nuovi dati del file, ma mantiene anche gli attributi seguenti del file originale:

Ora di creazione
Nome file breve
Identificatore dell'oggetto
DACLs
Attributi delle risorse di sicurezza
Codifica
Compressione
Flussi denominati non già presenti nel file di sostituzione

Ad esempio, se il file sostitutivo è crittografato, ma il file sostituito non è crittografato, il file risultante non viene crittografato.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Attributi delle risorse di sicurezza (ATTRIBUTE_SECURITY_INFORMATION) per il file originale non vengono mantenuti fino a Windows 8 e Windows Server 2012.

nota

Se il file sostitutivo è protetto tramite cancellazione selettiva, il file sostituito verrà protetto dall'ID organizzazione del file sostitutivo.

Il file risultante ha lo stesso ID file del file di sostituzione.

Il file di backup, il file sostituito e il file di sostituzione devono trovarsi tutti nello stesso volume.

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 vengono ereditati gli elenchi DACL dei nuovi file, sarà possibile creare un file senza poterlo eliminare. Tuttavia, è possibile creare un file e si otterrà tutto l'accesso richiesto sull'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.

Nota

L'intestazione winbase.h definisce ReplaceFile come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

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