Función CopyFileExA (winbase.h)
Copia un archivo existente en un nuevo archivo y notifica a la aplicación su progreso mediante una función de devolución de llamada.
Para realizar esta operación como una operación de transacción, use la función CopyFileTransact.
Sintaxis
BOOL CopyFileExA(
[in] LPCSTR lpExistingFileName,
[in] LPCSTR lpNewFileName,
[in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
[in, optional] LPVOID lpData,
[in, optional] LPBOOL pbCancel,
[in] DWORD dwCopyFlags
);
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 la función CopyFileEx y la función GetLastError devuelve ERROR_FILE_NOT_FOUND.
[in] lpNewFileName
Nombre del nuevo archivo.
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.
[in, optional] lpProgressRoutine
Dirección de una función de devolución de llamada de tipo LPPROGRESS_ROUTINE que se llama cada vez que se ha copiado otra parte del archivo. Este parámetro puede ser NULL. Para obtener más información sobre la función de devolución de llamada de progreso, consulte la función CopyProgressRoutine .
[in, optional] lpData
Argumento que se va a pasar a la función de devolución de llamada. Este parámetro puede ser NULL.
[in, optional] pbCancel
Si esta marca se establece en TRUE durante la operación de copia, se cancela la operación. De lo contrario, la operación de copia seguirá completando.
[in] dwCopyFlags
Marcas que especifican cómo se va a copiar el archivo. Este parámetro puede ser una combinación de los valores siguientes.
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.
Si lpProgressRoutine devuelve PROGRESS_CANCEL debido a que el usuario cancela la operación, CopyFileEx devolverá cero y GetLastError devolverá ERROR_REQUEST_ABORTED. En este caso, se elimina el archivo de destino parcialmente copiado.
Si lpProgressRoutine devuelve PROGRESS_STOP debido a que el usuario detiene la operación, CopyFileEx devolverá cero y GetLastError devolverá ERROR_REQUEST_ABORTED. En este caso, el archivo de destino parcialmente copiado se deja intacto.
Comentarios
Esta función conserva atributos extendidos, almacenamiento estructurado OLE, flujos de datos alternativos del sistema de archivos NTFS, atributos de recursos de seguridad y atributos de archivo.
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 existente no se copian en el nuevo archivo hasta Windows 8 y Windows Server 2012.
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.
Esta función produce un error 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 los archivos cifrados se copian mediante CopyFileEx, la función 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 pueden realizar ambos métodos, CopyFileEx produce un error ERROR_ENCRYPTION_FAILED código de error. Si desea que CopyFileEx complete la operación de copia incluso si no se puede cifrar el archivo de destino, incluya el COPY_FILE_ALLOW_DECRYPTED_DESTINATION como valor del parámetro dwCopyFlags en la llamada a CopyFileEx.
Si se especifica COPY_FILE_COPY_SYMLINK , se aplican las reglas siguientes:
- El archivo de origen es un vínculo simbólico, se copiará el vínculo simbólico, no el archivo de destino.
- El archivo de origen no es un vínculo simbólico, no habrá ningún cambio en el comportamiento.
- El archivo de destino es un vínculo simbólico existente, el vínculo simbólico se sobrescribirá, y no el archivo de destino.
- Si también se especifica COPY_FILE_FAIL_IF_EXISTS y el archivo de destino es un vínculo simbólico existente, se producirá un error en la operación en todos los casos.
- También se especifica COPY_FILE_FAIL_IF_EXISTS y el archivo de destino es un vínculo simbólico existente, se producirá un error solo si el destino del vínculo simbólico existe.
- Si no se especifica COPY_FILE_FAIL_IF_EXISTS, no habrá ningún cambio en el comportamiento.
Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Si está escribiendo una aplicación que optimiza las operaciones de copia de archivos en una LAN, considere la posibilidad de usar la función TransmitFile de Windows Sockets (Winsock). TransmitFile admite transferencias de red de alto rendimiento y proporciona una interfaz sencilla para enviar el contenido de un archivo a un equipo remoto. Para usar TransmitFile, debe escribir una aplicación cliente winsock que envíe el archivo desde el equipo de origen, así como una aplicación de servidor winsock que use otras funciones de Winsock para recibir el archivo en el equipo remoto.
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í |
Nota
El encabezado winbase.h define CopyFileEx 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 |
Vea también
Constantes de atributo de archivo