This topic has not yet been rated - Rate this topic

CopyFile2 function

[This documentation is preliminary and is subject to change.]

Applies to: desktop apps | Metro style apps

Copies an existing file to a new file, notifying the application of its progress through a callback function.

Syntax

Copy

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

If lpExistingFileName does not exist, the CopyFile2 function fails, and the GetLastError function returns HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND).

pwszNewFileName [in]

The name of the new file.

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
S_OK	The copy operation completed successfully.
HRESULT_FROM_WIN32(ERROR_REQUEST_PAUSED)	The copy operation was paused by a COPYFILE2_PROGRESS_PAUSE return from the CopyFile2ProgressRoutine callback function.
HRESULT_FROM_WIN32(ERROR_REQUEST_ABORTED)	The copy operation was paused by a COPYFILE2_PROGRESS_CANCEL or COPYFILE2_PROGRESS_STOP return from the CopyFile2ProgressRoutine callback function.
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)	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.
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)	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 0x0601 or later. For more information, see Using the Windows Headers.

Requirements