Función ReplaceFileW (winbase.h)

Artículo
06/02/2023

Reemplaza un archivo por otro, con la opción de crear una copia de seguridad del archivo original. El archivo de reemplazo supone el nombre del archivo reemplazado y su identidad.

Sintaxis

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

Parámetros

[in] lpReplacedFileName

Nombre del archivo que se va a reemplazar.

De forma predeterminada, el nombre está limitado a MAX_PATH caracteres. Para ampliar este límite a 32 767 caracteres anchos, anteponga "\\?\\ " a la ruta de acceso. Para obtener más información, vea Nomenclatura de archivos, rutas de acceso y espacios de nombres.

Sugerencia

A partir de Windows 10, versión 1607, puede optar por quitar la limitación de MAX_PATH sin prepending "\\?\". Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Nombres de archivos, rutas de acceso y espacios de nombres para obtener más información.

Este archivo se abre con los derechos de acceso GENERIC_READ, DELETE y SYNCHRONIZE . El modo de uso compartido se FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

El autor de la llamada debe tener acceso de escritura al archivo que se va a reemplazar. Para obtener más información, vea Derechos de acceso y seguridad de archivos.

[in] lpReplacementFileName

Nombre del archivo que reemplazará el archivo lpReplacedFileName .

Sugerencia

La función intenta abrir este archivo con los derechos de acceso SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE y WRITE_DAC para que pueda conservar todos los atributos y ACL. Si se produce un error, la función intenta abrir el archivo con los derechos de acceso SYNCHRONIZE, GENERIC_READ, DELETE y WRITE_DAC . No se especifica ningún modo de uso compartido.

[in, optional] lpBackupFileName

Nombre del archivo que servirá como copia de seguridad del archivo lpReplacedFileName . Si este parámetro es NULL, no se crea ningún archivo de copia de seguridad. Consulte la sección Comentarios para obtener detalles de implementación sobre el archivo de copia de seguridad.

Sugerencia

[in] dwReplaceFlags

Opciones de reemplazo. Este parámetro puede ser uno o más de los siguientes valores.

Valor	Significado
REPLACEFILE_WRITE_THROUGH 0x00000001	Este valor no se admite.
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	Omite los errores que se producen al combinar información (como atributos y ACL) del archivo reemplazado al archivo de reemplazo. Por lo tanto, si especifica esta marca y no tiene acceso WRITE_DAC , la función se realiza correctamente, pero las ACL no se conservan.
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	Omite los errores que se producen al combinar la información de ACL del archivo reemplazado al archivo de reemplazo. Por lo tanto, si especifica esta marca y no tiene acceso WRITE_DAC , la función se realiza correctamente, pero las ACL no se conservan. Para compilar una aplicación que use este valor, defina la macro _WIN32_WINNT como 0x0600 o posterior. Windows Server 2003 y Windows XP: Este valor no se admite.

lpExclude

Reservado para un uso futuro.

lpReserved

Reservado para un uso futuro.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError. A continuación se muestran los códigos de error posibles para esta función.

Código o valor devuelto	Descripción
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 (0x498)	No se pudo cambiar el nombre del archivo de reemplazo. Si se especificó lpBackupFileName , los archivos reemplazados y de reemplazo conservan sus nombres de archivo originales. De lo contrario, el archivo reemplazado ya no existe y el archivo de reemplazo existe bajo su nombre original.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 (0x499)	No se pudo mover el archivo de reemplazo. El archivo de reemplazo sigue existiendo bajo su nombre original; sin embargo, ha heredado los flujos de archivos y atributos del archivo que está reemplazando. El archivo que se va a reemplazar sigue existiendo con un nombre diferente. Si se especifica lpBackupFileName , será el nombre del archivo reemplazado.
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 (0x497)	No se pudo eliminar el archivo reemplazado. Los archivos reemplazados y de reemplazo conservan sus nombres de archivo originales.

Si se devuelve cualquier otro error, como ERROR_INVALID_PARAMETER, los archivos reemplazados y de reemplazo conservarán sus nombres de archivo originales. En este escenario, no existe un archivo de copia de seguridad y no se garantiza que el archivo de reemplazo haya heredado todos los atributos y secuencias del archivo reemplazado.

Comentarios

Propina A partir de Windows 10, versión 1607, para la versión unicode de esta función (ReplaceFileW), puede optar por quitar la limitación de MAX_PATH. Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Nombres de archivos, rutas de acceso y espacios de nombres para obtener más información.

La función ReplaceFile combina varios pasos dentro de una sola función. Una aplicación puede llamar a ReplaceFile en lugar de llamar a funciones independientes para guardar los datos en un nuevo archivo, cambiar el nombre del archivo original mediante un nombre temporal, cambiar el nombre del nuevo archivo para tener el mismo nombre que el archivo original y eliminar el archivo original. Otra ventaja es que ReplaceFile no solo copia los nuevos datos de archivo, sino que también conserva los siguientes atributos del archivo original:

Hora de creación
Nombre de archivo corto
Identificador de objeto
DACL
Atributos de recursos de seguridad
Cifrado
Compresión
Secuencias con nombre que aún no están en el archivo de reemplazo

Por ejemplo, si el archivo de reemplazo está cifrado, pero el archivo reemplazado no está cifrado, el archivo resultante no se cifra.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Los atributos de recursos de seguridad (ATTRIBUTE_SECURITY_INFORMATION) del archivo original no se conservan hasta Windows 8 y Windows Server 2012.

Nota

Si el archivo de reemplazo está protegido mediante borrado selectivo, el archivo reemplazado estará protegido por el identificador de empresa del archivo de reemplazo.

El archivo resultante tiene el mismo identificador de archivo que el archivo de reemplazo.

El archivo de copia de seguridad, el archivo reemplazado y el archivo de reemplazo deben residir en el mismo volumen.

Para eliminar o cambiar el nombre de un archivo, debe tener permiso de eliminación en el archivo o eliminar el permiso secundario en el directorio primario. Si configura un directorio con todo el acceso excepto eliminar y eliminar secundario y se heredan las DACL de nuevos archivos, debería poder crear un archivo sin poder eliminarlo. Sin embargo, puede crear un archivo y obtendrá todo el acceso que solicite en el identificador devuelto en el momento en que cree el archivo. Si solicitó el permiso de eliminación en el momento en que creó el archivo, podría eliminar o cambiar el nombre del archivo con ese identificador, pero no con ningún otro.

Nota

El encabezado winbase.h define ReplaceFile como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winbase.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll