CopyFileExA 함수(winbase.h)

아티클
06/02/2023

기존 파일을 새 파일에 복사하고, 콜백 함수를 통해 애플리케이션에 진행 상황을 알립니다.

이 작업을 트랜잭션 작업으로 수행하려면 CopyFileTransacted 함수를 사용합니다.

구문

BOOL CopyFileExA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags
);

매개 변수

[in] lpExistingFileName

기존 파일의 이름입니다.

기본적으로 이름은 MAX_PATH 문자로 제한됩니다. 이 제한을 32,767자로 확장하려면 경로에 "\\?\"를 앞에 추가합니다. 자세한 내용은 파일 이름 지정, 경로 및 네임스페이스를 참조하세요.

팁

Windows 10 버전 1607부터 "\\?\"를 앞에 추가하지 않고 MAX_PATH 제한을 제거하도록 옵트인할 수 있습니다. 자세한 내용은 파일, 경로 및 네임스페이스의 "최대 경로 길이 제한" 섹션을 참조하세요.

lpExistingFileName이 없으면 CopyFileEx 함수가 실패하고 GetLastError 함수가 ERROR_FILE_NOT_FOUND 반환합니다.

[in] lpNewFileName

새 파일의 이름입니다.

팁

[in, optional] lpProgressRoutine

파일의 다른 부분을 복사할 때마다 호출되는 형식 LPPROGRESS_ROUTINE 콜백 함수의 주소입니다. 이 매개 변수는 NULL일 수 있습니다. 진행률 콜백 함수에 대한 자세한 내용은 CopyProgressRoutine 함수를 참조하세요.

[in, optional] lpData

콜백 함수에 전달할 인수입니다. 이 매개 변수는 NULL일 수 있습니다.

[in, optional] pbCancel

복사 작업 중에 이 플래그가 TRUE 로 설정되면 작업이 취소됩니다. 그렇지 않으면 복사 작업이 계속 완료됩니다.

[in] dwCopyFlags

파일을 복사하는 방법을 지정하는 플래그입니다. 이 매개 변수는 다음 값의 조합일 수 있습니다.

값	의미
COPY_FILE_ALLOW_DECRYPTED_DESTINATION 0x00000008	대상 복사본을 암호화할 수 없더라도 암호화된 파일을 복사하려고 하면 성공합니다.
COPY_FILE_COPY_SYMLINK 0x00000800	원본 파일이 기호 링크인 경우 대상 파일은 원본 기호 링크가 가리키는 것과 동일한 파일을 가리키는 기호 링크이기도 합니다. Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	대상 파일이 이미 있는 경우 복사 작업이 즉시 실패합니다.
COPY_FILE_NO_BUFFERING 0x00001000	복사 작업은 시스템 I/O 캐시 리소스를 무시하고 버퍼링되지 않은 I/O를 사용하여 수행됩니다. 매우 큰 파일 전송에 권장됩니다. Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다.
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	파일이 복사되고 쓰기 액세스를 위해 원본 파일이 열립니다.
COPY_FILE_RESTARTABLE 0x00000002	복사가 실패할 경우 대상 파일에서 복사 진행률이 추적됩니다. 실패한 복사본은 실패한 호출에 사용된 값과 동일한 lpExistingFileName 및 lpNewFileName 값을 지정하여 나중에 다시 시작할 수 있습니다. 복사 작업 중에 새 파일이 여러 번 플러시될 수 있으므로 복사 작업의 속도가 크게 느려질 수 있습니다.
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC 0x10000000	복사 작업 중에 기본 전송 채널이 데이터를 압축할 것을 요청합니다. 요청은 모든 매체에 대해 지원되지 않을 수 있으며, 이 경우 무시됩니다. 압축 특성 및 매개 변수(계산 복잡성, 메모리 사용량)는 이 API를 통해 구성할 수 없으며 다른 OS 릴리스 간에 변경될 수 있습니다. 이 플래그는 Windows 10 버전 1903 및 Windows Server 2022에서 도입되었습니다. Windows 10 협상된 SMB 프로토콜 버전이 SMB v3.1.1 이상인 SMB 공유에 있는 파일에 대해 플래그가 지원됩니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 얻으려면 GetLastError를 호출합니다.

사용자가 작업을 취소하여 lpProgressRoutine 이 PROGRESS_CANCEL 반환하는 경우 CopyFileEx 는 0을 반환하고 GetLastError 는 ERROR_REQUEST_ABORTED 반환합니다. 이 경우 부분적으로 복사된 대상 파일이 삭제됩니다.

사용자가 작업을 중지하여 lpProgressRoutine 이 PROGRESS_STOP 반환하는 경우 CopyFileEx 는 0을 반환하고 GetLastError 는 ERROR_REQUEST_ABORTED 반환합니다. 이 경우 부분적으로 복사된 대상 파일은 그대로 유지됩니다.

설명

이 함수는 확장 특성, OLE 구조적 스토리지, NTFS 파일 시스템 대체 데이터 스트림, 보안 리소스 특성 및 파일 특성을 유지합니다.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 기존 파일에 대한 보안 리소스 특성(ATTRIBUTE_SECURITY_INFORMATION)은 Windows 8 Windows Server 2012 때까지 새 파일에 복사되지 않습니다.

기존 파일에 대한 보안 리소스 속성(ATTRIBUTE_SECURITY_INFORMATION)이 새 파일에 복사됩니다.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 기존 파일의 보안 리소스 속성은 Windows 8 Windows Server 2012 때까지 새 파일에 복사되지 않습니다.

대상 파일이 이미 있고 FILE_ATTRIBUTE_HIDDEN또는 FILE_ATTRIBUTE_READONLY 특성이 설정된 경우 이 함수는 ERROR_ACCESS_DENIED 실패합니다.

CopyFileEx를 사용하여 암호화된 파일을 복사하면 함수는 원본 파일의 암호화에 사용된 키로 대상 파일을 암호화하려고 시도합니다. 이 작업을 수행할 수 없는 경우 이 함수는 기본 키를 사용하여 대상 파일을 암호화하려고 시도합니다. 이러한 두 메서드를 모두 수행할 수 없는 경우 CopyFileEx 는 ERROR_ENCRYPTION_FAILED 오류 코드와 함께 실패합니다. 대상 파일을 암호화할 수 없는 경우에도 CopyFileEx가 복사 작업을 완료하도록 하려면 copyFileEx 호출에 dwCopyFlags 매개 변수 값으로 COPY_FILE_ALLOW_DECRYPTED_DESTINATION 포함합니다.

COPY_FILE_COPY_SYMLINK 지정한 경우 다음 규칙이 적용됩니다.

원본 파일이 바로 가기 링크인 경우 대상 파일이 아닌 바로 가기 링크가 복사됩니다.
원본 파일이 바로 가기 링크가 아니면 동작이 변경되지 않습니다.
대상 파일이 기존 바로 가기 링크인 경우 대상 파일이 아닌 바로 가기 링크가 덮어써집니다.
COPY_FILE_FAIL_IF_EXISTS도 지정되고 대상 파일이 기존 바로 가기 링크인 경우 모든 경우에 작업이 실패합니다.

COPY_FILE_COPY_SYMLINK 지정하지 않으면 다음 규칙이 적용됩니다.

COPY_FILE_FAIL_IF_EXISTS도 지정되었으며 대상 파일이 기존 바로 가기 링크인 경우 바로 가기 링크의 대상이 존재하는 경우에만 작업이 실패합니다.
COPY_FILE_FAIL_IF_EXISTS가 지정되지 않은 경우 동작이 변경되지 않습니다.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: LAN에서 파일 복사 작업을 최적화하는 애플리케이션을 작성하는 경우 Windows 소켓(Winsock)의 TransmissionFile 함수를 사용하는 것이 좋습니다. TransferFile 은 고성능 네트워크 전송을 지원하며 파일 내용을 원격 컴퓨터로 보내는 간단한 인터페이스를 제공합니다. TransmitFile을 사용하려면 원본 컴퓨터에서 파일을 보내는 Winsock 클라이언트 애플리케이션과 다른 Winsock 함수를 사용하여 원격 컴퓨터에서 파일을 수신하는 Winsock 서버 애플리케이션을 작성해야 합니다.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	Yes
SMB 3.0 TFO(투명 장애 조치(failover))	Yes
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	Yes
CsvFS(클러스터 공유 볼륨 파일 시스템)	Yes
ReFS(Resilient File System)	Yes

참고

winbase.h 헤더는 COPYFileEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	winbase.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll