ReplaceFileA, fonction (winbase.h)

Article
11/20/2024

Remplace un fichier par un autre fichier, par l’option de création d’une copie de sauvegarde du fichier d’origine. Le fichier de remplacement part du nom du fichier remplacé et de 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 larges, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez nommage des fichiers, des chemins d’accès et des espaces de noms.

Pourboire

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précéder « \\ ?\ ». Pour plus d’informations, consultez la section « Limite maximale de longueur de chemin » de noms, fichiers, chemin s et espaces de noms.

Ce fichier est ouvert avec le GENERIC_READ, DELETEet SYNCHRONISER droits d’accès. 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.

Pourboire

La fonction tente d’ouvrir ce fichier avec les droits d’accès SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETEet WRITE_DAC droits d’accès afin qu’il puisse conserver tous les attributs et ACL. Si cela échoue, la fonction tente d’ouvrir le fichier avec les droits d’accès SYNCHRONIZE, GENERIC_READ, DELETEet 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 est NULL, aucun fichier de sauvegarde n’est créé. Consultez la section Remarques pour plus d’informations sur l’implémentation sur le fichier de sauvegarde.

Pourboire

[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é au 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é au 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 une version ultérieure. Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.

lpExclude

Réservé pour une utilisation ultérieure.

lpReserved

Réservé pour une utilisation ultérieure.

Valeur de retour

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’erreur étendues, appelez GetLastError. Voici les codes d’erreur possibles pour cette fonction.

Retourner le code/la valeur	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 leurs noms de fichiers 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 autre nom. 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 leurs noms de fichiers d’origine.

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

Remarques

conseil à partir 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 « Limite maximale de longueur de chemin » de noms, fichiers, chemin s et espaces de noms.

La fonction ReplaceFile combine plusieurs étapes dans une seule 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 avoir 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
DACLs
Attributs de ressource de sécurité
Chiffrement
Compression
Flux nommés non 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 : attributs de ressources de sécurité (ATTRIBUTE_SECURITY_INFORMATION) pour le fichier d’origine ne sont pas conservés tant que Windows 8 et Windows Server 2012 ne sont pas conservés.

note

Si le fichier de remplacement est protégé à l’aide de 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 d’une autorisation de suppression 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 la suppression et de la suppression d’enfants et que les DACL de nouveaux fichiers sont hérités, vous devriez pouvoir créer un fichier sans pouvoir le supprimer. Toutefois, vous pouvez ensuite créer un fichier et obtenir tout l’accès que vous demandez sur le handle retourné au moment de la création du fichier. Si vous avez demandé l’autorisation de suppression au moment de la création du fichier, vous pouvez supprimer ou renommer le fichier avec ce handle, mais pas avec d’autres.

Note

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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll