CopyFileExA 함수(winbase.h)
기존 파일을 새 파일에 복사하고, 콜백 함수를 통해 애플리케이션에 진행 상황을 알립니다.
이 작업을 트랜잭션 작업으로 수행하려면 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
새 파일의 이름입니다.
기본적으로 이름은 MAX_PATH 문자로 제한됩니다. 이 제한을 32,767자로 확장하려면 경로에 "\\?\"를 앞에 추가합니다. 자세한 내용은 파일 이름 지정, 경로 및 네임스페이스를 참조하세요.
팁
Windows 10 버전 1607부터 "\\?\"를 앞에 추가하지 않고 MAX_PATH 제한을 제거하도록 옵트인할 수 있습니다. 자세한 내용은 파일, 경로 및 네임스페이스의 "최대 경로 길이 제한" 섹션을 참조하세요.
[in, optional] lpProgressRoutine
파일의 다른 부분을 복사할 때마다 호출되는 형식 LPPROGRESS_ROUTINE 콜백 함수의 주소입니다. 이 매개 변수는 NULL일 수 있습니다. 진행률 콜백 함수에 대한 자세한 내용은 CopyProgressRoutine 함수를 참조하세요.
[in, optional] lpData
콜백 함수에 전달할 인수입니다. 이 매개 변수는 NULL일 수 있습니다.
[in, optional] pbCancel
복사 작업 중에 이 플래그가 TRUE 로 설정되면 작업이 취소됩니다. 그렇지 않으면 복사 작업이 계속 완료됩니다.
[in] dwCopyFlags
파일을 복사하는 방법을 지정하는 플래그입니다. 이 매개 변수는 다음 값의 조합일 수 있습니다.
반환 값
함수가 성공하면 반환 값이 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_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 |