MoveFileTransactedA 함수(winbase.h)

[Microsoft는 개발자가 애플리케이션의 요구 사항을 달성하기 위해 대체 수단을 활용하는 것이 좋습니다. TxF가 개발된 많은 시나리오는 더 간단하고 쉽게 사용할 수 있는 기술을 통해 달성할 수 있습니다. 또한 이후 버전의 Microsoft Windows에서는 TxF를 사용하지 못할 수도 있습니다. TxF에 대한 자세한 내용과 대안은 트랜잭션 NTFS 사용에 대한 대안을 참조하세요.]

트랜잭션 작업으로 자식을 포함한 기존 파일 또는 디렉터리를 이동합니다.

구문

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

매개 변수

[in] lpExistingFileName

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

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

팁

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

[in, optional] lpNewFileName

파일 또는 디렉터리의 새 이름입니다. 새 이름이 아직 없어야 합니다. 새 파일이 다른 파일 시스템 또는 드라이브에 있을 수 있습니다. 새 디렉터리가 동일한 드라이브에 있어야 합니다.

기본적으로 이름은 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_REPLACE_EXISTING 1(0x1)	lpNewFileName이라는 파일이 있는 경우 함수는 해당 내용을 lpExistingFileName 파일의 내용으로 바꿉니다. lpNewFileName 또는 lpExistingFileName이 디렉터리의 이름을 지정하는 경우 이 값을 사용할 수 없습니다.
MOVEFILE_WRITE_THROUGH 8(0x8)	MoveFileTransacted 호출은 커밋 작업이 완료되면 파일 이동 작업이 완료됨을 의미합니다. 이 플래그는 필요하지 않습니다. 이 플래그를 지정하면 작업 속도가 느려지는 것 외에는 부정적인 영향이 없습니다. 파일이 실제로 디스크에서 이동될 때까지 함수는 반환되지 않습니다. 이 값을 설정하면 함수가 반환되기 전에 복사 및 삭제 작업으로 수행된 이동이 디스크로 플러시됩니다. 플러시 는 복사 작업이 끝날 때 발생합니다. MOVEFILE_DELAY_UNTIL_REBOOT 설정된 경우에는 이 값이 적용되지 않습니다.

[in] hTransaction

트랜잭션에 대한 핸들입니다. 이 핸들은 CreateTransaction 함수에 의해 반환됩니다.

반환 값

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

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

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

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

설명

dwFlags 매개 변수가 MOVEFILE_DELAY_UNTIL_REBOOT 지정하면 레지스트리에 액세스할 수 없는 경우 MoveFileTransacted가 실패합니다. 함수는 다시 시작할 때 이름을 바꿀 파일의 위치를 트랜잭션 방식으로 저장합니다. HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations

이 레지스트리 값은 REG_MULTI_SZ 형식입니다. 각 이름 바꾸기 작업은 이름 바꾸기가 삭제인지 여부에 따라 다음 NULL로 끝나는 문자열 중 하나를 저장합니다.

szDstFile\0\0

szSrcFile\0szDstFile\0

szDstFile\0\0 문자열은 다시 부팅 시 szDstFile 파일을 삭제할 것임을 나타냅니다.

szSrcFile\0szDstFile\0 문자열은 다시 부팅 시 szSrcFile의 이름을 szDstFile으로 변경해야 했음을 나타냅니다.

참고 \0\0은 REG_MULTI_SZ 노드에서 기술적으로 허용되지 않지만 파일 이름이 null 이름으로 변경된 것으로 간주되기 때문일 수 있습니다.

 

시스템은 이러한 레지스트리 항목을 사용하여 다시 시작할 때 발급된 것과 동일한 순서로 작업을 완료합니다. MOVEFILE_DELAY_UNTIL_REBOOT 플래그를 사용하는 방법에 대한 자세한 내용은 MoveFileWithProgress를 참조하세요.

파일이 볼륨 간에 이동되는 경우 MoveFileTransacted 는 파일과 함께 보안 설명자를 이동하지 않습니다. 파일에 대상 디렉터리에 기본 보안 설명자가 할당됩니다.

MOVEFILE_FAIL_IF_NOT_TRACKABLE 플래그를 지정하면 이 함수는 항상 실패합니다. 추적은 TxF에서 지원되지 않습니다.

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

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

 

SMB 3.0은 TxF를 지원하지 않습니다.

요구 사항

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

참고 항목

CopyFileTransacted

파일 관리 함수

MoveFileWithProgress

트랜잭션 NTFS