ReplaceFileA, fonction (winbase.h)

Article
06/02/2023

Remplace un fichier par un autre fichier, avec la possibilité de créer une copie de sauvegarde du fichier d’origine. Le fichier de remplacement suppose le nom du fichier remplacé et son identité.

Syntaxe

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

Paramètres

[in] lpReplacedFileName

Nom du fichier à remplacer.

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères de large, ajoutez « \\?\ » au chemin d’accès. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.

Conseil

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation de MAX_PATH sans précédencer « \?\ ». Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans Naming Files, Paths et Namespaces .

Ce fichier est ouvert avec les droits d’accès GENERIC_READ, DELETE et SYNCHRONIZE . Le mode de partage est FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

L’appelant doit avoir un accès en écriture au fichier à remplacer. Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.

[in] lpReplacementFileName

Nom du fichier qui remplacera le fichier lpReplacedFileName .

Conseil

La fonction tente d’ouvrir ce fichier avec les droits d’accès SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE et WRITE_DAC afin qu’elle puisse conserver tous les attributs et listes de contrôle d’accès. En cas d’échec, la fonction tente d’ouvrir le fichier avec les droits d’accès SYNCHRONIZE, GENERIC_READ, DELETE et WRITE_DAC . Aucun mode de partage n’est spécifié.

[in, optional] lpBackupFileName

Nom du fichier qui servira de copie de sauvegarde du fichier lpReplacedFileName . Si ce paramètre a la valeur NULL, aucun fichier de sauvegarde n’est créé. Pour plus d’informations sur l’implémentation du fichier de sauvegarde, consultez la section Remarques.

Conseil

[in] dwReplaceFlags

Options de remplacement. Ce paramètre peut être une ou plusieurs des valeurs suivantes.

Valeur	Signification
REPLACEFILE_WRITE_THROUGH 0x00000001	Cette valeur n’est pas prise en charge.
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	Ignore les erreurs qui se produisent lors de la fusion d’informations (telles que les attributs et les listes de contrôle d’accès) du fichier remplacé vers le fichier de remplacement. Par conséquent, si vous spécifiez cet indicateur et que vous n’avez pas d’accès WRITE_DAC , la fonction réussit, mais les listes de contrôle d’accès ne sont pas conservées.
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	Ignore les erreurs qui se produisent lors de la fusion des informations de liste de contrôle d’accès du fichier remplacé vers le fichier de remplacement. Par conséquent, si vous spécifiez cet indicateur et que vous n’avez pas d’accès WRITE_DAC , la fonction réussit, mais les listes de contrôle d’accès ne sont pas conservées. Pour compiler une application qui utilise cette valeur, définissez la macro _WIN32_WINNT comme 0x0600 ou version ultérieure. Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.

lpExclude

Réservé à un usage ultérieur.

lpReserved

Réservé à un usage ultérieur.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. Voici les codes d’erreur possibles pour cette fonction.

Code/valeur de retour	Description
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 (0x498)	Impossible de renommer le fichier de remplacement. Si lpBackupFileName a été spécifié, les fichiers remplacés et de remplacement conservent leur nom de fichier d’origine. Sinon, le fichier remplacé n’existe plus et le fichier de remplacement existe sous son nom d’origine.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 (0x499)	Impossible de déplacer le fichier de remplacement. Le fichier de remplacement existe toujours sous son nom d’origine ; toutefois, il a hérité les flux de fichiers et les attributs du fichier qu’il remplace. Le fichier à remplacer existe toujours avec un nom différent. Si lpBackupFileName est spécifié, il s’agit du nom du fichier remplacé.
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 (0x497)	Impossible de supprimer le fichier remplacé. Les fichiers remplacés et de remplacement conservent leur nom de fichier d’origine.

Si une autre erreur est retournée, telle que ERROR_INVALID_PARAMETER, les fichiers remplacés et de remplacement conservent leur nom de fichier d’origine. Dans ce scénario, un fichier de sauvegarde n’existe pas et il n’est pas garanti que le fichier de remplacement aura hérité de tous les attributs et flux du fichier remplacé.

Notes

Pointe À compter de Windows 10, version 1607, pour la version Unicode de cette fonction (ReplaceFileW), vous pouvez choisir de supprimer la limitation MAX_PATH. Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans Naming Files, Paths et Namespaces .

La fonction ReplaceFile combine plusieurs étapes au sein d’une même fonction. Une application peut appeler ReplaceFile au lieu d’appeler des fonctions distinctes pour enregistrer les données dans un nouveau fichier, renommer le fichier d’origine à l’aide d’un nom temporaire, renommer le nouveau fichier pour qu’il ait le même nom que le fichier d’origine et supprimer le fichier d’origine. Un autre avantage est que ReplaceFile copie non seulement les nouvelles données de fichier, mais conserve également les attributs suivants du fichier d’origine :

Heure de création
Nom de fichier court
Identificateur d'objet
DACL
Attributs de ressource de sécurité
Chiffrement
Compression
Flux nommés qui ne sont pas déjà dans le fichier de remplacement

Par exemple, si le fichier de remplacement est chiffré, mais que le fichier remplacé n’est pas chiffré, le fichier résultant n’est pas chiffré.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Les attributs de ressource de sécurité (ATTRIBUTE_SECURITY_INFORMATION) du fichier d’origine ne sont pas conservés tant que Windows 8 et Windows Server 2012.

Remarque

Si le fichier de remplacement est protégé à l’aide de la réinitialisation sélective, le fichier remplacé est protégé par l’ID d’entreprise du fichier de remplacement.

Le fichier résultant a le même ID de fichier que le fichier de remplacement.

Le fichier de sauvegarde, le fichier remplacé et le fichier de remplacement doivent tous résider sur le même volume.

Pour supprimer ou renommer un fichier, vous devez disposer de l’autorisation supprimer sur le fichier ou supprimer l’autorisation enfant dans le répertoire parent. Si vous configurez un répertoire avec tous les accès à l’exception de delete et delete child et que les DACL de nouveaux fichiers sont hérités, vous devriez être en mesure de créer un fichier sans pouvoir le supprimer. Toutefois, vous pouvez ensuite créer un fichier, et vous obtiendrez tous les accès que vous demandez sur le handle retourné au moment où vous créez le fichier. Si vous avez demandé l’autorisation de suppression au moment où vous avez créé le fichier, vous pouvez supprimer ou renommer le fichier avec ce handle, mais pas avec un autre.

Notes

L’en-tête winbase.h définit ReplaceFile comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll