다음을 통해 공유

MoveFileWithProgressA 함수(winbase.h)

  • 아티클

자식을 포함한 파일 또는 디렉터리를 이동합니다. 진행률 알림을 받는 콜백 함수를 제공할 수 있습니다.

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

구문

BOOL MoveFileWithProgressA(
  [in]           LPCSTR             lpExistingFileName,
  [in, optional] LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in]           DWORD              dwFlags
);

매개 변수

[in] lpExistingFileName

로컬 컴퓨터의 기존 파일 또는 디렉터리의 이름입니다.

dwFlags에서 MOVEFILE_DELAY_UNTIL_REBOOT 지정하는 경우 네트워크를 사용할 수 있기 전에 지연된 작업이 수행되므로 원격 공유에 파일이 있을 수 없습니다.

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

팁

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

[in, optional] lpNewFileName

로컬 컴퓨터의 파일 또는 디렉터리의 새 이름입니다.

파일을 이동할 때 lpNewFileName 은 다른 파일 시스템 또는 볼륨에 있을 수 있습니다. lpNewFileName이 다른 드라이브에 있는 경우 dwFlags에서 MOVEFILE_COPY_ALLOWED 플래그를 설정해야 합니다.

디렉터리를 이동할 때 lpExistingFileName 및 lpNewFileName 은 동일한 드라이브에 있어야 합니다.

dwFlags가 MOVEFILE_DELAY_UNTIL_REBOOT 지정하고 lpNewFileName이 NULL인 경우 MoveFileWithProgress는 시스템이 다시 시작될 때 삭제할 lpExistingFileName을 등록합니다. 삭제 작업에 대한 정보를 저장하기 위해 레지스트리에 액세스할 수 없는 경우 함수가 실패합니다. lpExistingFileName이 디렉터리를 참조하는 경우 시스템은 디렉터리가 비어 있는 경우에만 다시 시작할 때 디렉터리를 제거합니다.

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

팁

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

[in, optional] lpProgressRoutine

파일의 다른 부분을 이동할 때마다 호출되는 CopyProgressRoutine 콜백 함수에 대한 포인터입니다. 콜백 함수는 작업의 진행률을 표시하는 사용자 인터페이스를 제공하는 경우에 유용할 수 있습니다. 이 매개 변수는 NULL일 수 있습니다.

[in, optional] lpData

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

[in] dwFlags

이동 옵션입니다. 이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

값 의미
MOVEFILE_COPY_ALLOWED
2(0x2)
 파일을 다른 볼륨으로 이동하려는 경우 함수는 CopyFile 및 DeleteFile 함수를 사용하여 이동을 시뮬레이션합니다.

파일이 다른 볼륨에 성공적으로 복사되고 원래 파일을 삭제할 수 없는 경우 함수는 원본 파일을 그대로 유지합니다.

이 값은 MOVEFILE_DELAY_UNTIL_REBOOT 사용할 수 없습니다.
MOVEFILE_CREATE_HARDLINK
16(0x10)
 다음에 사용하도록 예약됩니다.
MOVEFILE_DELAY_UNTIL_REBOOT
4(0x4)
 운영 체제가 다시 시작될 때까지 시스템은 파일을 이동하지 않습니다. 시스템은 AUTOCHK가 실행된 직후에 페이징 파일을 만들기 전에 파일을 이동합니다. 따라서 이 매개 변수를 사용하면 함수가 이전 시작에서 페이징 파일을 삭제할 수 있습니다.

이 값은 프로세스가 관리자 그룹 또는 LocalSystem 계정에 속한 사용자의 컨텍스트에 있는 경우에만 사용할 수 있습니다.

이 값은 MOVEFILE_COPY_ALLOWED 사용할 수 없습니다.
MOVEFILE_FAIL_IF_NOT_TRACKABLE
32(0x20)
 원본 파일이 링크 원본이지만 이동 후 파일을 추적할 수 없으면 함수가 실패합니다. 이 상황은 대상이 FAT 파일 시스템으로 포맷된 볼륨인 경우에 발생할 수 있습니다.
MOVEFILE_REPLACE_EXISTING
1(0x1)
 lpNewFileName이라는 파일이 있는 경우 함수는 해당 내용을 lpExistingFileName 파일의 내용으로 바꿉니다.

lpNewFileName 또는 lpExistingFileName이 디렉터리의 이름을 지정하는 경우 이 값을 사용할 수 없습니다.
MOVEFILE_WRITE_THROUGH
8(0x8)
 파일이 실제로 디스크에서 이동될 때까지 함수는 반환되지 않습니다.

이 값을 설정하면 함수가 반환되기 전에 복사 및 삭제 작업으로 수행된 이동이 디스크로 플러시됩니다. 플러시 는 복사 작업이 끝날 때 발생합니다.

MOVEFILE_DELAY_UNTIL_REBOOT 설정된 경우에는 이 값이 적용되지 않습니다.

반환 값

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

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

볼륨 간에 파일을 이동할 때 사용자가 작업을 취소하여 lpProgressRoutine 이 PROGRESS_CANCEL 반환하는 경우 MoveFileWithProgress 는 0을 반환하고 GetLastError 는 ERROR_REQUEST_ABORTED 반환합니다. 기존 파일은 그대로 유지됩니다.

볼륨 간에 파일을 이동할 때 사용자가 작업을 중지하여 lpProgressRoutine 이 PROGRESS_STOP 반환하는 경우 MoveFileWithProgress 는 0을 반환하고 GetLastError 는 ERROR_REQUEST_ABORTED 반환합니다. 기존 파일은 그대로 유지됩니다.

설명

MoveFileWithProgress 함수는 링크 추적 서비스와 작업을 조정하므로 링크 원본이 이동될 때 추적할 수 있습니다.

파일을 삭제하거나 이름을 바꾸려면 파일에 대한 삭제 권한이 있거나 부모 디렉터리에서 자식 권한을 삭제해야 합니다. 하위 삭제 및 삭제를 제외한 모든 액세스 권한이 있는 디렉터리를 설정하고 새 파일의 ACL이 상속되는 경우 파일을 삭제하지 않고도 만들 수 있어야 합니다. 그러나 파일을 만들 수 있으며 파일을 만들 때 반환된 핸들에 대해 요청하는 모든 액세스 권한을 얻을 수 있습니다. 파일을 만들 때 삭제 권한을 요청한 경우 해당 핸들을 사용하여 파일을 삭제하거나 이름을 바꿀 수 있지만 다른 핸들은 삭제하거나 이름을 바꿀 수 없습니다.

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) 예
 

CsvF는 압축된 파일에 대해 리디렉션된 IO를 수행합니다.

참고

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

요구 사항

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

참고 항목

CopyFileEx

CopyProgressRoutine

파일 관리 함수

MoveFileEx

MoveFileTransacted