ReplaceFileA-Funktion (winbase.h)

Artikel
06/02/2023

Ersetzt eine Datei durch eine andere Datei mit der Option, eine Sicherungskopie der ursprünglichen Datei zu erstellen. Die Ersatzdatei setzt den Namen der ersetzten Datei und deren Identität voraus.

Syntax

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

Parameter

[in] lpReplacedFileName

Der Name der zu ersetzenden Datei.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um dieses Limit auf 32.767 breite Zeichen zu erweitern, müssen Sie dem Pfad "\\?\" voranstellen. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Tipp

Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung entfernen, ohne "\\?\" vorauszustellen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .

Diese Datei wird mit den Zugriffsberechtigungen GENERIC_READ, DELETE und SYNCHRONIZE geöffnet. Der Freigabemodus wird FILE_SHARE_WRITE FILE_SHARE_DELETE | | FILE_SHARE_READ.

Der Aufrufer muss Schreibzugriff auf die zu ersetzende Datei haben. Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte.

[in] lpReplacementFileName

Der Name der Datei, die die lpReplacedFileName-Datei ersetzt.

Tipp

Die Funktion versucht, diese Datei mit den Zugriffsrechten SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE und WRITE_DAC zu öffnen, sodass alle Attribute und ACLs beibehalten werden können. Wenn dies fehlschlägt, versucht die Funktion, die Datei mit den Zugriffsrechten SYNCHRONIZE, GENERIC_READ, DELETE und WRITE_DAC zu öffnen. Es ist kein Freigabemodus angegeben.

[in, optional] lpBackupFileName

Der Name der Datei, die als Sicherungskopie der lpReplacedFileName-Datei dient. Wenn dieser Parameter NULL ist, wird keine Sicherungsdatei erstellt. Details zur Implementierung der Sicherungsdatei finden Sie im Abschnitt Hinweise.

Tipp

[in] dwReplaceFlags

Die Ersatzoptionen. Bei diesem Parameter kann es sich um einen oder mehrere der folgenden Werte handeln.

Wert	Bedeutung
REPLACEFILE_WRITE_THROUGH 0x00000001	Dieser Wert wird nicht unterstützt.
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	Ignoriert Fehler, die beim Zusammenführen von Informationen (z. B. Attribute und ACLs) aus der ersetzten Datei in die Ersatzdatei auftreten. Wenn Sie dieses Flag angeben und keinen WRITE_DAC Zugriff haben, ist die Funktion erfolgreich, die ACLs werden jedoch nicht beibehalten.
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	Ignoriert Fehler, die beim Zusammenführen von ACL-Informationen aus der ersetzten Datei mit der Ersatzdatei auftreten. Wenn Sie dieses Flag angeben und keinen WRITE_DAC Zugriff haben, ist die Funktion erfolgreich, die ACLs werden jedoch nicht beibehalten. Um eine Anwendung zu kompilieren, die diesen Wert verwendet, definieren Sie das _WIN32_WINNT Makro als 0x0600 oder höher. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.

lpExclude

Für zukünftige Verwendung reserviert.

lpReserved

Für zukünftige Verwendung reserviert.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Im Folgenden finden Sie mögliche Fehlercodes für diese Funktion.

Rückgabecode/-wert	BESCHREIBUNG
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 (0x498)	Die Ersatzdatei konnte nicht umbenannt werden. Wenn lpBackupFileName angegeben wurde, behalten die ersetzten und ersetzungsdateien ihre ursprünglichen Dateinamen bei. Andernfalls ist die ersetzte Datei nicht mehr vorhanden, und die Ersatzdatei ist unter ihrem ursprünglichen Namen vorhanden.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 (0x499)	Die Ersatzdatei konnte nicht verschoben werden. Die Ersatzdatei ist weiterhin unter ihrem ursprünglichen Namen vorhanden. Die Dateidatenströme und -attribute wurden jedoch von der ersetzten Datei geerbt. Die zu ersetzende Datei ist weiterhin mit einem anderen Namen vorhanden. Wenn lpBackupFileName angegeben wird, ist dies der Name der ersetzten Datei.
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 (0x497)	Die ersetzte Datei konnte nicht gelöscht werden. Die ersetzten dateien und ersatzdateien behalten ihre ursprünglichen Dateinamen bei.

Wenn ein anderer Fehler zurückgegeben wird, z. B. ERROR_INVALID_PARAMETER, behalten die ersetzten dateien und die Ersetzungsdateien ihre ursprünglichen Dateinamen bei. In diesem Szenario ist keine Sicherungsdatei vorhanden, und es ist nicht garantiert, dass die Ersatzdatei alle Attribute und Streams der ersetzten Datei geerbt hat.

Bemerkungen

Tipp Ab Windows 10 Version 1607 für die Unicode-Version dieser Funktion (ReplaceFileW) können Sie die MAX_PATH-Einschränkung entfernen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .

Die ReplaceFile-Funktion kombiniert mehrere Schritte innerhalb einer einzelnen Funktion. Eine Anwendung kann ReplaceFile aufrufen, anstatt separate Funktionen zum Speichern der Daten in einer neuen Datei aufzurufen, die ursprüngliche Datei mit einem temporären Namen umbenennen, die neue Datei so umbenennen, dass sie denselben Namen wie die ursprüngliche Datei hat, und die ursprüngliche Datei löschen. Ein weiterer Vorteil ist, dass ReplaceFile nicht nur die neuen Dateidaten kopiert, sondern auch die folgenden Attribute der ursprünglichen Datei behält:

Erstellungszeitpunkt
Kurzer Dateiname
Objektbezeichner
DACLs
Sicherheitsressourcenattribute
Verschlüsselung
Komprimierung
Benannte Streams, die noch nicht in der Ersatzdatei enthalten sind

Wenn beispielsweise die Ersatzdatei verschlüsselt ist, die ersetzte Datei jedoch nicht verschlüsselt ist, wird die resultierende Datei nicht verschlüsselt.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Sicherheitsressourcenattribute (ATTRIBUTE_SECURITY_INFORMATION) für die ursprüngliche Datei werden erst beibehalten, wenn Windows 8 und Windows Server 2012.

Hinweis

Wenn die Ersatzdatei durch selektives Zurücksetzen geschützt ist, wird die ersetzte Datei durch die Enterprise-ID der Ersatzdatei geschützt.

Die resultierende Datei hat dieselbe Datei-ID wie die Ersatzdatei.

Die Sicherungsdatei, die ersetzte Datei und die Ersatzdatei müssen sich auf demselben Volume befinden.

Um eine Datei zu löschen oder umzubenennen, müssen Sie entweder über die Löschberechtigung für die Datei oder über die untergeordnete Berechtigung im übergeordneten Verzeichnis verfügen. Wenn Sie ein Verzeichnis mit allen Zugriffen mit Ausnahme des untergeordneten Lösch- und Löschvorgangs einrichten und die DACLs neuer Dateien geerbt werden, sollten Sie eine Datei erstellen können, ohne sie löschen zu können. Sie können dann jedoch eine Datei erstellen, und Sie erhalten den gesamten Zugriff, den Sie zum Zeitpunkt der Erstellung der Datei anfordern, auf das Handle zurückgegeben. Wenn Sie zum Zeitpunkt der Erstellung der Datei die Löschberechtigung angefordert haben, können Sie die Datei mit diesem Handle löschen oder umbenennen, aber nicht mit einem anderen.

Hinweis

Der winbase.h-Header definiert ReplaceFile als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll