Función CopyFile2 (winbase.h)

  • Artículo

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.

Sintaxis

HRESULT CopyFile2(
  [in]           PCWSTR                        pwszExistingFileName,
  [in]           PCWSTR                        pwszNewFileName,
  [in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);

Parámetros

[in] pwszExistingFileName

Nombre de un archivo existente.

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.

Propina A partir de Windows 10, versión 1607, puedes optar por quitar la limitación de caracteres de MAX_PATH sin prepending "\\?\". Consulte la sección "Limitación máxima de rutas 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 CopyFile2.HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)

[in] pwszNewFileName

Nombre del nuevo archivo.

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.

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

[in, optional] pExtendedParameters

Dirección opcional de una estructura de COPYFILE2_EXTENDED_PARAMETERS .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto devolverá TRUE cuando se pase a la macro SUCCEEDED .

Código devuelto Descripción
S_OK
 La operación de copia se completó correctamente.
HRESULT_FROM_WIN32(ERROR_REQUEST_PAUSED)
 La operación de copia se ha pausado mediante una COPYFILE2_PROGRESS_PAUSE devolución de la función de devolución de llamada CopyFile2ProgressRoutine .
HRESULT_FROM_WIN32(ERROR_REQUEST_ABORTED)
 Una COPYFILE2_PROGRESS_CANCEL o COPYFILE2_PROGRESS_STOP devolvió la operación de copia desde la función de devolución de llamada CopyFile2ProgressRoutine .
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)
 El miembro dwCopyFlags de la estructura COPYFILE2_EXTENDED_PARAMETERS que se pasa a través del parámetro pExtendedParameters contiene la marca COPY_FILE_FAIL_IF_EXISTS y existe un nombre en conflicto.
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)
 El miembro dwCopyFlags de la estructura COPYFILE2_EXTENDED_PARAMETERS que se pasa a través del parámetro pExtendedParameters contiene la marca COPY_FILE_FAIL_IF_EXISTS y existe un nombre en conflicto.

Comentarios

Esta función conserva los atributos extendidos, el almacenamiento estructurado OLE, los flujos de datos alternativos del sistema de archivos NTFS y los atributos de archivo. Los atributos de seguridad del archivo existente no se copian en el nuevo archivo. Para copiar atributos de seguridad, use la función SHFileOperation .

Esta función produce un error si HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) el archivo de destino ya existe y tiene el FILE_ATTRIBUTE_HIDDEN o FILE_ATTRIBUTE_READONLY atributo establecido.

Para compilar una aplicación que usa esta función, defina la macro _WIN32_WINNT como _WIN32_WINNT_WIN8 o posterior. Para obtener más información, vea Usar los encabezados de Windows.

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í

A partir de Windows 10, versión 1903 y Windows Server 2022, se admite un nuevo valor, COPY_FILE_REQUEST_COMPRESSED_TRAFFIC, para el campo dwCopyFlags de la estructura de COPYFILE2_EXTENDED_PARAMETERS pasado en el argumento pExtendedParameters a esta función. Este nuevo valor solicita que el canal de transferencia subyacente comprima los datos durante la operación de copia. Es posible que la solicitud no se admita para todos los medios, en cuyo caso se omite. Los atributos y parámetros de compresión (complejidad computacional, uso de memoria) no se pueden configurar a través de esta API y están sujetos a cambios entre diferentes versiones del sistema operativo. En Windows 10, la marca es compatible con los archivos que residen en recursos compartidos SMB, donde la versión negociada del protocolo SMB es SMB v3.1.1 o superior.

Requisitos

   
Cliente mínimo compatible Windows 8 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2012 [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

COPYFILE2_EXTENDED_PARAMETERS

Funciones de administración de archivos