CopyFileExA 함수(winbase.h)

아티클
11/20/2024

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

이 작업을 트랜잭션 작업으로 수행하려면 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을 반환하고 GetLastErrorERROR_REQUEST_ABORTED반환합니다. 이 경우 부분적으로 복사된 대상 파일이 삭제됩니다.

사용자가 작업을 중지하여 lpProgressRoutinePROGRESS_STOP 반환하는 경우 CopyFileEx 0을 반환하고 GetLastErrorERROR_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사용하여 암호화된 파일을 복사하면 함수는 원본 파일의 암호화에 사용되는 키를 사용하여 대상 파일을 암호화하려고 시도합니다. 이 작업을 수행할 수 없는 경우 이 함수는 기본 키를 사용하여 대상 파일을 암호화하려고 시도합니다. 이러한 두 메서드를 모두 수행할 수 없는 경우 CopyFileExERROR_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)의 TransmitFile 함수를 사용하는 것이 좋습니다. TransmitFile 고성능 네트워크 전송을 지원하고 파일 내용을 원격 컴퓨터로 보내는 간단한 인터페이스를 제공합니다. TransmitFile사용하려면 원본 컴퓨터에서 파일을 보내는 Winsock 클라이언트 애플리케이션과 다른 Winsock 함수를 사용하여 원격 컴퓨터에서 파일을 수신하는 Winsock 서버 애플리케이션을 작성해야 합니다.

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

기술	지원
SMB(서버 메시지 블록) 3.0 프로토콜	예
SMB 3.0 TFO(투명한 장애 조치(failover)	예
SO(스케일 아웃 파일 공유)가 있는 SMB 3.0	예
CsvFS(클러스터 공유 볼륨 파일 시스템)	예
ReFS(복원 파일 시스템)	예

메모

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

요구 사항

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