CopyFileTransacted function
[This documentation is preliminary and is subject to change.]
Copies an existing file to a new file as a transacted operation, notifying the application of its progress through a callback function.
Syntax
BOOL WINAPI CopyFileTransacted( _In_ LPCTSTR lpExistingFileName, _In_ LPCTSTR lpNewFileName, _In_opt_ LPPROGRESS_ROUTINE lpProgressRoutine, _In_opt_ LPVOID lpData, _In_opt_ LPBOOL pbCancel, _In_ DWORD dwCopyFlags, _In_ HANDLE hTransaction );
Parameters
- lpExistingFileName [in]
-
The name of an existing file.
In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see Naming a File.
If lpExistingFileName does not exist, the CopyFileTransacted function fails, and the GetLastError function returns ERROR_FILE_NOT_FOUND.
The file must reside on the local computer; otherwise, the function fails and the last error code is set to ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.
- lpNewFileName [in]
-
The name of the new file.
In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see Naming a File.
- lpProgressRoutine [in, optional]
-
The address of a callback function of type LPPROGRESS_ROUTINE that is called each time another portion of the file has been copied. This parameter can be NULL. For more information on the progress callback function, see the CopyProgressRoutine function.
- lpData [in, optional]
-
The argument to be passed to the callback function. This parameter can be NULL.
- pbCancel [in, optional]
-
If this flag is set to TRUE during the copy operation, the operation is canceled. Otherwise, the copy operation will continue to completion.
- dwCopyFlags [in]
-
Flags that specify how the file is to be copied. This parameter can be a combination of the following values.
- hTransaction [in]
-
A handle to the transaction. This handle is returned by the CreateTransaction function.
Return value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information call GetLastError.
If lpProgressRoutine returns PROGRESS_CANCEL due to the user canceling the operation, CopyFileTransacted will return zero and GetLastError will return ERROR_REQUEST_ABORTED. In this case, the partially copied destination file is deleted.
If lpProgressRoutine returns PROGRESS_STOP due to the user stopping the operation, CopyFileTransacted will return zero and GetLastError will return ERROR_REQUEST_ABORTED. In this case, the partially copied destination file is left intact.
If you attempt to call this function with a handle to a transaction that has already been rolled back, CopyFileTransacted will return either ERROR_TRANSACTION_NOT_ACTIVE or ERROR_INVALID_TRANSACTION.
Remarks
This function preserves extended attributes, OLE structured storage, NTFS file system alternate data streams, security attributes, and file attributes.
Windows 7, Windows Server 2008 R2, Windows Server 2008, and Windows Vista: Security attributes for the existing file are not copied to the new file until Windows Developer Preview and Windows Server Developer Preview.
This function fails with ERROR_ACCESS_DENIED if the destination file already exists and has the FILE_ATTRIBUTE_HIDDEN or FILE_ATTRIBUTE_READONLY attribute set.
Encrypted files are not supported by TxF.
If COPY_FILE_COPY_SYMLINK is specified, the following rules apply:
- If the source file is a symbolic link, the symbolic link is copied, not the target file.
- If the source file is not a symbolic link, there is no change in behavior.
- If the destination file is an existing symbolic link, the symbolic link is overwritten, not the target file.
- If COPY_FILE_FAIL_IF_EXISTS is also specified, and the destination file is an existing symbolic link, the operation fails in all cases.
If COPY_FILE_COPY_SYMLINK is not specified, the following rules apply:
- If COPY_FILE_FAIL_IF_EXISTS is also specified, and the destination file is an existing symbolic link, the operation fails only if the target of the symbolic link exists.
- If COPY_FILE_FAIL_IF_EXISTS is not specified, there is no change in behavior.
Link tracking is not supported by TxF.
Requirements
|
Minimum supported client | Windows Vista |
|---|---|
|
Minimum supported server | Windows Server 2008 |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | CopyFileTransactedW (Unicode) and CopyFileTransactedA (ANSI) |
See also
- CopyProgressRoutine
- CreateFileTransacted
- MoveFileTransacted
- File Attribute Constants
- File Management Functions
- Symbolic Links
- Transactional NTFS
Build date: 9/10/2011
Sebastien.
- 12/21/2009
- Sebastien Bovo
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
internal static extern bool CopyFileTransacted([In] string lpExistingFileName, [In] string lpNewFileName, [In] IntPtr lpProgressRoutine, [In] IntPtr lpData, [In, MarshalAs(UnmanagedType.Bool)] ref bool pbCancel, [In] CopyFileFlags dwCopyFlags, [In] KtmTransactionHandle hTransaction);
- 4/21/2009
- dmex
<DllImport("kernel32.dll", CharSet:=CharSet.Unicode, SetLastError:=True)> Public Shared Function CopyFileTransacted(<[In]> ByVal lpExistingFileName As String, <[In]> ByVal lpNewFileName As String, <[In]> ByVal lpProgressRoutine As IntPtr, <[In]> ByVal lpData As IntPtr, <[In], MarshalAs(UnmanagedType.Bool)> ByRef pbCancel As Boolean, <[In]> ByVal dwCopyFlags As CopyFileFlags, <[In]> ByVal hTransaction As KtmTransactionHandle) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function
- 4/21/2009
- dmex