CopyFile2 function
Copies an existing file to a new file, notifying the application of its progress through a callback function.
Syntax
HRESULT WINAPI CopyFile2( _In_ PCWSTR pwszExistingFileName, _In_ PCWSTR pwszNewFileName, _In_opt_ COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters );
Parameters
- pwszExistingFileName [in]
-
The name of an existing file.
To extend this limit to 32,767 wide characters, prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.
Tip Starting in Windows 10, version 1607, you can opt-in to remove the MAX_PATH character limitation without prepending "\\?\". See the "Maximum Path Limitation" section of Naming Files, Paths, and Namespaces for details.If lpExistingFileName does not exist, the CopyFile2 function fails returns
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND). - pwszNewFileName [in]
-
The name of the new file.
To extend this limit to 32,767 wide characters, prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.
Tip Starting in Windows 10, version 1607, you can opt-in to remove the MAX_PATH character limitation without prepending "\\?\". See the "Maximum Path Limitation" section of Naming Files, Paths, and Namespaces for details. - pExtendedParameters [in, optional]
-
Optional address of a COPYFILE2_EXTENDED_PARAMETERS structure.
Return value
If the function succeeds, the return value will return TRUE when passed to the SUCCEEDED macro.
| Return code | Description |
|---|---|
|
The copy operation completed successfully. |
|
The copy operation was paused by a COPYFILE2_PROGRESS_PAUSE return from the CopyFile2ProgressRoutine callback function. |
|
The copy operation was paused by a COPYFILE2_PROGRESS_CANCEL or COPYFILE2_PROGRESS_STOP return from the CopyFile2ProgressRoutine callback function. |
|
The dwCopyFlags member of the COPYFILE2_EXTENDED_PARAMETERS structure passed through the pExtendedParameters parameter contains the COPY_FILE_FAIL_IF_EXISTS flag and a conflicting name existed. |
|
The dwCopyFlags member of the COPYFILE2_EXTENDED_PARAMETERS structure passed through the pExtendedParameters parameter contains the COPY_FILE_FAIL_IF_EXISTS flag and a conflicting name existed. |
Remarks
This function preserves extended attributes, OLE structured storage, NTFS file system alternate data streams, and file attributes. Security attributes for the existing file are not copied to the new file. To copy security attributes, use the SHFileOperation function.
This function fails with
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) if the destination
file already exists and has the FILE_ATTRIBUTE_HIDDEN or
FILE_ATTRIBUTE_READONLY attribute set.
To compile an application that uses this function, define the _WIN32_WINNT macro as _WIN32_WINNT_WIN8 or later. For more information, see Using the Windows Headers.
In Windows 8 and Windows Server 2012, this function is supported by the following technologies.
| Technology | Supported |
|---|---|
|
Server Message Block (SMB) 3.0 protocol |
Yes |
|
SMB 3.0 Transparent Failover (TFO) |
Yes |
|
SMB 3.0 with Scale-out File Shares (SO) |
Yes |
|
Cluster Shared Volume File System (CsvFS) |
Yes |
|
Resilient File System (ReFS) |
Yes |
Requirements
|
Minimum supported client |
Windows 8 [desktop apps | Windows Store apps] |
|---|---|
|
Minimum supported server |
Windows Server 2012 [desktop apps | Windows Store apps] |
|
Minimum supported phone |
Windows Phone 8 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also