CopyFileEx

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function copies an existing file to a new file.

Syntax

BOOL CopyFileEx(
  LPCTSTR lpExistingFileName, 
  LPCTSTR lpNewFileName,
  LPPROGRESS_ROUTINE lpProgressRoutine,
  LPVOID lpData,
  LPBOOL pbCancel,
  DWORD dwCopyFlags
);

Parameters

  • lpExistingFileName
    [in] Pointer to a null-terminated string that specifies the name of an existing file.
  • lpNewFileName
    [in] Pointer to a null-terminated string that specifies the name of the new file.
  • lpProgressRoutine
    [in] Address of a callback function that is called each time another portion of the file has been copied. This parameter can be set to NULL.
  • lpData
    [in] Parameter to be passed to the callback function. This parameter can be set to NULL.
  • pbCancel
    [in] If this parameter is set to TRUE during the copy operation, the operation is canceled. Otherwise, the copy operation continues to completion.

  • dwCopyFlags
    [in] Flags that specify how the file is to be copied. This parameter can be set to any combination of the values shown in the following table.

    Value Description

    COPY_FILE_ALLOW_DECRYPTED_DESTINATION

    An attempt to copy an encrypted file succeeds, even if the destination copy cannot be encrypted.

    COPY_FILE_FAIL_IF_EXISTS

    The copy operation fails immediately if the target file already exists.

    COPY_FILE_RESTARTABLE

    Progress of the copy is tracked in the target file in case the copy fails. The failed copy can be restarted at a later time by specifying the same values for lpExistingFileName and lpNewFileName as those used in the call that failed.

Return Value

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

This function fails with ERROR_ACCESS_DENIED if the destination file already exists and has the FILE_ATTRIBUTE_HIDDEN or the FILE_ATTRIBUTE_READONLY file attribute set.

If lpProgressRoutine returns PROGRESS_CANCEL because the user cancels the operation, this function returns zero, and GetLastError returns ERROR_REQUEST_ABORTED. In this case, the partially copied destination file is deleted.

If lpProgressRoutine returns PROGRESS_STOP because the user stops the operation, this function returns zero, and GetLastError returns ERROR_REQUEST_ABORTED. In this case, the partially copied destination file is left intact.

Requirements

Header winbase.h
Library coredll.lib
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

File I/O Functions
CopyFile
CreateFile
MoveFile
DeleteAndRenameFile