CopyFile2 function (winbase.h)
Copies an existing file to a new file, notifying the application of its progress through a callback function.
Syntax
HRESULT CopyFile2(
[in] PCWSTR pwszExistingFileName,
[in] PCWSTR pwszNewFileName,
[in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);
Parameters
[in] pwszExistingFileName
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.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND).
[in] pwszNewFileName
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.
[in, optional] pExtendedParameters
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 |
Starting with Windows 10, version 1903 and Windows Server 2022, a new value, COPY_FILE_REQUEST_COMPRESSED_TRAFFIC, is supported for the dwCopyFlags field of the COPYFILE2_EXTENDED_PARAMETERS structure passed in the pExtendedParameters argument to this function. This new value requests that the underlying transfer channel compress the data during the copy operation. The request may not be supported for all mediums, in which case it is ignored. The compression attributes and parameters (computational complexity, memory usage) are not configurable through this API, and are subject to change between different OS releases. On Windows 10, the flag is supported for files residing on SMB shares, where the negotiated SMB protocol version is SMB v3.1.1 or greater.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2012 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | winbase.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |