Función CopyFile (winbase.h)

Artículo
03/13/2024

Copia un archivo existente en un archivo nuevo.

La función CopyFileEx proporciona dos funcionalidades adicionales. CopyFileEx puede llamar a una función de devolución de llamada especificada cada vez que se completa una parte de la operación de copia y CopyFileEx se puede cancelar durante la operación de copia.

Para realizar esta operación como una operación de transacción, use la función CopyFileTransacted .

Sintaxis

BOOL CopyFile(
  [in] LPCTSTR lpExistingFileName,
  [in] LPCTSTR lpNewFileName,
  [in] BOOL    bFailIfExists
);

Parámetros

[in] lpExistingFileName

Nombre de un archivo existente.

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.

Si lpExistingFileName no existe, se produce un error en CopyFile y GetLastError devuelve ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

Nombre del nuevo archivo.

Sugerencia

[in] bFailIfExists

Si este parámetro es TRUE y el nuevo archivo especificado por lpNewFileName ya existe, se produce un error en la función. Si este parámetro es FALSE y el nuevo archivo ya existe, la función sobrescribe el archivo existente y se ejecuta correctamente.

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.

Comentarios

Las propiedades del recurso de seguridad (ATTRIBUTE_SECURITY_INFORMATION) del archivo existente se copian en el nuevo archivo.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Las propiedades de recursos de seguridad del archivo existente no se copian en el nuevo archivo hasta que Windows 8 y Windows Server 2012.

Los atributos de archivo del archivo existente se copian en el nuevo archivo. Por ejemplo, si un archivo existente tiene el atributo de archivo FILE_ATTRIBUTE_READONLY , una copia creada a través de una llamada a CopyFile también tendrá el atributo de archivo FILE_ATTRIBUTE_READONLY . Para obtener más información, vea Recuperar y cambiar atributos de archivo.

Se produce un error en esta función con ERROR_ACCESS_DENIED si el archivo de destino ya existe y tiene el FILE_ATTRIBUTE_HIDDEN o FILE_ATTRIBUTE_READONLY conjunto de atributos.

Cuando CopyFile se usa para copiar un archivo cifrado, intenta cifrar el archivo de destino con las claves usadas en el cifrado del archivo de origen. Si esto no se puede hacer, esta función intenta cifrar el archivo de destino con claves predeterminadas. Si no se puede realizar ninguno de estos métodos, CopyFile produce un error ERROR_ENCRYPTION_FAILED código de error.

Comportamiento de vínculo simbólico: si el archivo de origen es un vínculo simbólico, el archivo real copiado es el destino del vínculo simbólico.

Si el archivo de destino ya existe y es un vínculo simbólico, el archivo de origen sobrescribe el destino del vínculo simbólico.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

Ejemplos

Para obtener un ejemplo, vea Recuperar y cambiar atributos de archivo.

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