ReplaceFileA-Funktion (winbase.h)

Artikel
11/20/2024

Ersetzt eine Datei durch eine andere Datei durch die Option zum Erstellen einer Sicherungskopie der ursprünglichen Datei. Die Ersetzungsdatei 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 diesen Grenzwert auf 32.767 breite Zeichen zu erweitern, stellen Sie "\\?\" dem Pfad voran. Weitere Informationen finden Sie unter Namensdateien, Pfade und Namespaces.

Trinkgeld

Ab Windows 10, Version 1607, können Sie sich anmelden, um die MAX_PATH Einschränkung zu entfernen, ohne "\\?\". Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbeschränkung" Benennungsdateien, Pfade und Namespaces.

Diese Datei wird mit dem GENERIC_READ, DELETE-und SYNCHRONIZE Zugriffsrechte geöffnet. Der Freigabemodus ist FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

Der Aufrufer muss Schreibzugriff auf die zu ersetzende Datei haben. Weitere Informationen finden Sie unter Dateisicherheits- und Zugriffsberechtigungen.

[in] lpReplacementFileName

Der Name der Datei, die den lpReplacedFileName Datei ersetzt.

Trinkgeld

Die Funktion versucht, diese Datei mit dem SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETEzu öffnen, und WRITE_DAC Zugriffsrechte, damit alle Attribute und ACLs erhalten bleiben können. Wenn dies fehlschlägt, versucht die Funktion, die Datei mit dem SYNCHRONIZE, GENERIC_READ, DELETEund WRITE_DAC Zugriffsrechten zu öffnen. Es ist kein Freigabemodus angegeben.

[in, optional] lpBackupFileName

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

Trinkgeld

[in] dwReplaceFlags

Die Ersatzoptionen. Dieser Parameter kann einen oder mehrere der folgenden Werte sein.

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. Attributen und ACLs) aus der ersetzten Datei in die Ersetzungsdatei auftreten. Wenn Sie dieses Flag angeben und nicht über WRITE_DAC Zugriff verfügen, wird die Funktion erfolgreich ausgeführt, die ACLs werden jedoch nicht beibehalten.
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	Ignoriert Fehler, die beim Zusammenführen von ACL-Informationen aus der ersetzten Datei in die Ersetzungsdatei auftreten. Wenn Sie dieses Flag angeben und nicht über WRITE_DAC Zugriff verfügen, wird die Funktion erfolgreich ausgeführt, 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

Reserviert für die zukünftige Verwendung.

lpReserved

Reserviert für die zukünftige Verwendung.

Rückgabewert

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

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten. Nachfolgend finden Sie mögliche Fehlercodes für diese Funktion.

Zurückgeben von Code/Wert	Beschreibung
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 (0x498)	Die Ersetzungsdatei 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 Ersetzungsdatei ist unter dem ursprünglichen Namen vorhanden.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 (0x499)	Die Ersetzungsdatei konnte nicht verschoben werden. Die Ersetzungsdatei ist noch unter ihrem ursprünglichen Namen vorhanden; Sie hat jedoch die Dateidatenströme und Attribute von der Datei geerbt, die sie ersetzt. Die zu ersetzende Datei ist weiterhin mit einem anderen Namen vorhanden. Wenn lpBackupFileName angegeben wird, ist es der Name der ersetzten Datei.
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 (0x497)	Die ersetzte Datei konnte nicht gelöscht werden. Die ersetzten und ersetzten Dateien behalten ihre ursprünglichen Dateinamen bei.

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

Bemerkungen

Tipp Ab Windows 10, Version 1607, für die Unicode-Version dieser Funktion (ReplaceFileW), können Sie sich anmelden, um die MAX_PATH Einschränkung zu entfernen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbeschränkung" Benennungsdateien, Pfade und Namespaces.

Die funktion ReplaceFile 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 umzubenennen, die neue Datei umzubenennen, um denselben Namen wie die Originaldatei zu haben, 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 beibehalten:

Erstellungszeit
Kurzer Dateiname
Objektbezeichner
DACLs
Sicherheitsressourcenattribute
Verschlüsselung
Kompression
Benannte Datenströme, die noch nicht in der Ersetzungsdatei enthalten sind

Wenn die Ersetzungsdatei beispielsweise 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 Originaldatei werden erst beibehalten, wenn Windows 8 und Windows Server 2012.

Wenn die Ersetzungsdatei mit Selektive Zurücksetzunggeschützt ist, wird die ersetzte Datei durch die Unternehmens-ID der Ersetzungsdatei geschützt.

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

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

Um eine Datei zu löschen oder umzubenennen, müssen Sie entweder über die Berechtigung zum Löschen der Datei oder über die Berechtigung zum Löschen untergeordneter Elemente im übergeordneten Verzeichnis verfügen. Wenn Sie ein Verzeichnis mit allen Zugriffen einrichten, mit Ausnahme des Löschens und Löschens untergeordneter Elemente, und die DACLs neuer Dateien geerbt werden, sollten Sie in der Lage sein, eine Datei zu erstellen, ohne sie löschen zu können. Sie können dann jedoch eine Datei erstellen, und Sie erhalten alle Zugriffe, die Sie beim Erstellen der Datei an Sie erhalten. 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 anderen.

Anmerkung

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

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll