Compartir a través de

Función ReplaceFileA (winbase.h)

  • Artículo

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

Sintaxis

BOOL ReplaceFileA(
  [in]           LPCSTR lpReplacedFileName,
  [in]           LPCSTR lpReplacementFileName,
  [in, optional] LPCSTR 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 se limita 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 Archivos de nomenclatura, rutas de acceso y espacios de nombres.

Propina

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

Este archivo se abre con los derechos de acceso de GENERIC_READ, DELETEy SYNCHRONIZE. El modo de uso compartido es 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.

De forma predeterminada, el nombre se limita 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 Archivos de nomenclatura, rutas de acceso y espacios de nombres.

Propina

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

La función intenta abrir este archivo con los SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETEy WRITE_DAC derechos de acceso para que pueda conservar todos los atributos y ACL. Si se produce un error, la función intenta abrir el archivo con la SYNCHRONIZE, GENERIC_READ, DELETEy WRITE_DAC derechos de acceso. 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.

De forma predeterminada, el nombre se limita 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 Archivos de nomenclatura, rutas de acceso y espacios de nombres.

Propina

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

[in] dwReplaceFlags

Opciones de reemplazo. Este parámetro puede ser uno o varios 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 WRITE_DAC acceso, 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 WRITE_DAC acceso, 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 uso futuro.

lpReserved

Reservado para uso futuro.

Valor devuelto

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

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

Código y valor devueltos 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 archivo y los atributos del archivo que está reemplazando. El archivo que se va a reemplazar todavía existe 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.

Observaciones

sugerencia 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 Archivos de nomenclatura, 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
  • Encriptación
  • 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: Atributos de recursos de seguridad (ATTRIBUTE_SECURITY_INFORMATION) para el archivo original no se conservan hasta Windows 8 y Windows Server 2012.

nota  

Si el archivo de reemplazo está protegido mediante de 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 permiso secundario en el directorio primario. Si configura un directorio con todo el acceso excepto eliminar y eliminar secundario y las DACL de los nuevos archivos se heredan, 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 Conventions for Function Prototypes.

Requisitos

Requisito Valor
cliente mínimo admitido Windows XP [aplicaciones de escritorio | Aplicaciones para UWP]
servidor mínimo admitido Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP]
de la plataforma de destino de Windows
encabezado de winbase.h (incluya Windows.h)
biblioteca de Kernel32.lib
DLL de Kernel32.dll

Consulte también

CopyFile

CopyFileEx

funciones de administración de archivos

MoveFile

MoveFileEx

MoveFileWithProgress