Función CopyFileTransactedA (winbase.h)

Artículo
11/20/2024

[Microsoft recomienda encarecidamente que los desarrolladores usen medios alternativos para lograr las necesidades de la aplicación. Muchos escenarios para los que se desarrolló TxF se pueden lograr a través de técnicas más sencillas y disponibles con mayor facilidad. Además, es posible que TxF no esté disponible en versiones futuras de Microsoft Windows. Para obtener más información y alternativas a TxF, consulte Alternativas al uso de NTFS transaccional.]

Copia un archivo existente en un nuevo archivo como una operación de transacción, notificando a la aplicación su progreso a través de una función de devolución de llamada.

Sintaxis

BOOL CopyFileTransactedA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags,
  [in]           HANDLE             hTransaction
);

Parámetros

[in] lpExistingFileName

Nombre de un archivo existente.

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.>.

Si no existe lpExistingFileName, la función CopyFileTransacted produce un error y la función GetLastError devuelve ERROR_FILE_NOT_FOUND.

El archivo debe residir en el equipo local; De lo contrario, se produce un error en la función y el último código de error se establece en ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] lpNewFileName

Nombre del nuevo archivo.

Propina

[in, optional] lpProgressRoutine

Dirección de una función de devolución de llamada de tipo LPPROGRESS_ROUTINE a la 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 continuará completando.

[in] dwCopyFlags

Marcas que especifican cómo se va a copiar el archivo. Este parámetro puede ser una combinación de los siguientes valores.

Valor	Significado
COPY_FILE_COPY_SYMLINK 0x00000800	Si el archivo de origen es un vínculo simbólico, el archivo de destino también es un vínculo simbólico que apunta al mismo archivo al que apunta el vínculo simbólico de origen.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	La operación de copia produce un error inmediatamente si el archivo de destino ya existe.
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	El archivo se copia y el archivo original se abre para el acceso de escritura.
COPY_FILE_RESTARTABLE 0x00000002	Se realiza un seguimiento del progreso de la copia en el archivo de destino en caso de que se produzca un error en la copia. La copia con errores se puede reiniciar más adelante especificando los mismos valores para lpExistingFileName y lpNewFileName como los usados en la llamada que produjo un error. Esto puede ralentizar significativamente la operación de copia, ya que el nuevo archivo se puede vaciar varias veces durante la operación de copia.

[in] hTransaction

Identificador de la transacción. El función createTransaction devuelve este identificador.

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 la llamada de información de error extendida GetLastError.

Si lpProgressRoutine devuelve PROGRESS_CANCEL debido a que el usuario cancela la operación, CopyFileTransacted devolverá cero y GetLastError devolverá ERROR_REQUEST_ABORTED. En este caso, se elimina el archivo de destino copiado parcialmente.

Si lpProgressRoutine devuelve PROGRESS_STOP debido a que el usuario detiene la operación, copyFileTransacted devolverá cero y getLastError devolverá ERROR_REQUEST_ABORTED. En este caso, el archivo de destino copiado parcialmente se deja intacto.

Si intenta llamar a esta función con un identificador a una transacción que ya se ha revertido, CopyFileTransacted devolverá ERROR_TRANSACTION_NOT_ACTIVE o ERROR_INVALID_TRANSACTION.

Observaciones

Esta función conserva atributos extendidos, almacenamiento estructurado OLE, flujos de datos alternativos del sistema de archivos NTFS, atributos de seguridad y atributos de archivo.

Windows 7, Windows Server 2008 R2, Windows Server 2008 y Windows Vista: Atributos de recursos de seguridad (ATTRIBUTE_SECURITY_INFORMATION) para el archivo existente no se copian en el nuevo archivo hasta 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 atributo establecido.

TxF no admite archivos cifrados.

Si se especifica COPY_FILE_COPY_SYMLINK, se aplican las reglas siguientes:

Si el archivo de origen es un vínculo simbólico, se copia el vínculo simbólico, no el archivo de destino.
Si el archivo de origen no es un vínculo simbólico, no hay ningún cambio en el comportamiento.
Si el archivo de destino es un vínculo simbólico existente, el vínculo simbólico se sobrescribe, 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 produce un error en la operación en todos los casos.

Si no se especifica COPY_FILE_COPY_SYMLINK, se aplican las reglas siguientes:

Si también se especifica COPY_FILE_FAIL_IF_EXISTS y el archivo de destino es un vínculo simbólico existente, la operación produce un error solo si existe el destino del vínculo simbólico.
Si no se especifica COPY_FILE_FAIL_IF_EXISTS, no hay ningún cambio en el comportamiento.

TxF no admite el seguimiento de vínculos.

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

Tecnología	Soportado
Protocolo bloque de mensajes del servidor (SMB) 3.0	No
Conmutación por error transparente (TFO) de SMB 3.0	No
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	No
Sistema de archivos de volumen compartido de clúster (CsvFS)	No
Sistema de archivos resistente (ReFS)	No

Tenga en cuenta que SMB 3.0 no admite TxF.

Nota

El encabezado winbase.h define CopyFileTransacted 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 Vista [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2008 [solo aplicaciones de escritorio]
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

CopyProgressRoutine

CreateFileTransacted

constantes de atributo de archivo de

funciones de administración de archivos

moveFileTransacted

vínculos simbólicos

NTFS transaccional

Compartir a través de