ReplaceFileFromAppW, fonction (fileapifromapp.h)

Article
08/23/2023

Remplace un fichier par un autre, avec la possibilité de créer une copie de sauvegarde du fichier original. Le comportement de cette fonction est identique à ReplaceFile, sauf que cette fonction adhère au modèle de sécurité d’application plateforme Windows universelle.

Syntaxe

WINSTORAGEAPI BOOL ReplaceFileFromAppW(
  LPCWSTR lpReplacedFileName,
  LPCWSTR lpReplacementFileName,
  LPCWSTR lpBackupFileName,
  DWORD   dwReplaceFlags,
  LPVOID  lpExclude,
  LPVOID  lpReserved
) noexcept;

Paramètres

lpReplacedFileName

Pour plus d’informations sur la désactivation de la limitation de MAX_PATH sans passer à la limite « \??\ », consultez la section « Limitation de longueur maximale du chemin d’accès » de l’article Nommage des fichiers, des chemins et des espaces de noms .

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.

lpReplacementFileName

Nom du fichier qui remplacera le fichier lpReplacedFileName .

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é.

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.

dwReplaceFlags

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

Valeur	Signification
0x00000001 REPLACEFILE_WRITE_THROUGH	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.
0x00000004 REPLACEFILE_IGNORE_ACL_ERRORS	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.

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é.

Spécifications


Client minimal pris en charge	Windows 10 version 1803
En-tête	fileapifromapp.h