Funzione ReplaceFileA (winbase.h)

Articolo
06/02/2023

Sostituisce un file con un altro file, con l'opzione di creazione di 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, 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 .

Questo file viene aperto con i diritti di accesso GENERIC_READ, DELETE e SYNC . 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 Sicurezza file e diritti di accesso.

[in] lpReplacementFileName

Nome del file che sostituirà il file lpReplacedFileName .

Suggerimento

La funzione tenta di aprire questo file con SYNC, GENERIC_READ, GENERIC_WRITE, DELETE e WRITE_DAC diritti di accesso in modo che possa mantenere tutti gli attributi e gli elenchi di controllo di accesso. In caso contrario, la funzione tenta di aprire il file con SYNC,GENERIC_READ, DELETE e WRITE_DAC diritti di accesso. 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.

Suggerimento

[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 sostitutivo. 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 sostitutivo. 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 usi futuri.

lpReserved

Riservato per usi futuri.

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

Codice/valore restituito	Descrizione
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 (0x498)	Impossibile rinominare il file di sostituzione. Se lpBackupFileName è stato specificato, i file sostituiti e sostitutivi mantengono i nomi di 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 originali dei file.

Se viene restituito qualsiasi altro errore, ad esempio ERROR_INVALID_PARAMETER, i file sostituiti e sostitutivi manterranno i relativi 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.

Commenti

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

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

Tempo di creazione
Nome file breve
Identificatori di oggetto
DACL
Attributi delle risorse di sicurezza
Crittografia
Compressione
Flussi denominati non già 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: Gli 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 di sostituzione è protetto tramite cancellazione selettiva, il file sostituito sarà protetto dall'ID organizzazione del file sostitutivo.

Il file risultante ha lo stesso ID file del file sostitutivo.

Il file di backup, il file sostituito e il file sostitutivo devono risiedere 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 tutto l'accesso, ad eccezione dell'eliminazione e dell'eliminazione figlio e le dll DAC dei nuovi file vengono ereditate, è consigliabile essere in grado di 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.

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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll