Export (0) Print
Expand All
Expand Minimize

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

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.

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 codeDescription
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 _WIN32_WINNT_WIN8 or later. For more information, see Using the Windows Headers.

Windows Phone 8: This API is supported.

Windows Phone 8.1: This API is supported.

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

TechnologySupported

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]

Header

WinBase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

File Management Functions
COPYFILE2_EXTENDED_PARAMETERS

 

 

Community Additions

ADD
Show:
© 2014 Microsoft