SHFileOperationA 함수(shellapi.h)
파일 시스템 개체를 복사, 이동, 이름 바꾸기 또는 삭제합니다. 이 함수는 Windows Vista에서 IFileOperation으로 대체되었습니다.
구문
int SHFileOperationA(
[in, out] LPSHFILEOPSTRUCTA lpFileOp
);
매개 변수
[in, out] lpFileOp
형식: LPSHFILEOPSTRUCT
이 함수가 지정된 작업을 수행하는 데 필요한 정보를 포함하는 SHFILEOPSTRUCT 구조체에 대한 포인터입니다. 이 매개 변수는 NULL이 아닌 유효한 값을 포함해야 합니다. 값의 유효성을 검사할 책임이 있습니다. 유효성을 검사하지 않으면 예기치 않은 결과가 발생합니다.
반환 값
형식: int
성공하면 0을 반환합니다. 그렇지 않으면 0이 아닌 값입니다. 애플리케이션은 일반적으로 0 또는 0이 아닌 경우 단순히 검사 합니다.
SHFILEOPSTRUCT의 fAnyOperationsAborted 멤버 값을 검사하는 것이 좋습니다. 사용자가 작업을 취소하는 경우 SHFileOperation은 성공에 대해 0을 반환할 수 있습니다. 반환 값뿐만 아니라 fAnyOperationsAborted를 검사 않으면 함수가 요청한 전체 작업을 수행했음을 알 수 없으며 잘못된 가정으로 진행할 수 있습니다.
이 함수의 반환 값과 함께 GetLastError 를 사용하지 마세요.
문제 해결을 위해 0이 아닌 값을 검사하기 위해 주로 Winerror.h에 정의된 값에 매핑됩니다. 그러나 가능한 반환 값 중 일부는 Win32 이전 오류 코드를 기반으로 하며, 경우에 따라 의미와 일치하지 않고 이후 Winerror.h 값과 겹치는 경우도 있습니다. 이러한 특정 값은 여기에 자세히 설명되어 있으며 이러한 특정 값의 경우 이러한 의미만 Winerror.h 코드를 통해 수락되어야 합니다. 그러나 이러한 값은 다음과 같은 경고와 함께 제공됩니다.
- 이러한 코드는 Win32 이전 오류 코드이며 더 이상 공용 헤더 파일에서 지원되거나 정의되지 않습니다. 이를 사용하려면 직접 정의하거나 숫자 값과 비교해야 합니다.
- 이러한 오류 코드는 변경될 수 있으며 지금까지 변경되었습니다.
- 이러한 값은 디버깅에 도움이 되는 것으로만 제공됩니다. 그들은 결정적인 것으로 간주되어서는 안됩니다.
| 오류 코드 | 값 | 의미 |
|---|---|---|
| DE_SAMEFILE | 0x71 | 원본 및 대상 파일은 동일한 파일입니다. |
| DE_MANYSRC1DEST | 0x72 | 원본 버퍼에 여러 파일 경로가 지정되었지만 대상 파일 경로는 하나만 지정되었습니다. |
| DE_DIFFDIR | 0x73 | 이름 바꾸기 작업이 지정되었지만 대상 경로가 다른 디렉터리입니다. 대신 이동 작업을 사용합니다. |
| DE_ROOTDIR | 0x74 | 원본은 이동하거나 이름을 바꿀 수 없는 루트 디렉터리입니다. |
| DE_OPCANCELLED | 0x75 | 사용자가 작업을 취소했거나 해당 플래그가 SHFileOperation에 제공된 경우 자동으로 취소되었습니다. |
| DE_DESTSUBTREE | 0x76 | 대상은 원본의 하위 트리입니다. |
| DE_ACCESSDENIEDSRC | 0x78 | 보안 설정에서 원본에 대한 액세스가 거부되었습니다. |
| DE_PATHTOODEEP | 0x79 | 원본 또는 대상 경로가 MAX_PATH 초과하거나 초과합니다. |
| DE_MANYDEST | 0x7A | 작업에는 이동 작업의 경우 실패할 수 있는 여러 대상 경로가 포함되었습니다. |
| DE_INVALIDFILES | 0x7C | 원본 또는 대상 또는 둘 다의 경로가 잘못되었습니다. |
| DE_DESTSAMETREE | 0x7D | 원본과 대상의 부모 폴더가 동일합니다. |
| DE_FLDDESTISFILE | 0x7E | 대상 경로는 기존 파일입니다. |
| DE_FILEDESTISFLD | 0x80 | 대상 경로는 기존 폴더입니다. |
| DE_FILENAMETOOLONG | 0x81 | 파일 이름이 MAX_PATH 초과합니다. |
| DE_DEST_IS_CDROM | 0x82 | 대상은 읽기 전용 CD-ROM이며 형식이 지정되지 않은 것일 수 있습니다. |
| DE_DEST_IS_DVD | 0x83 | 대상은 서식이 없는 읽기 전용 DVD입니다. |
| DE_DEST_IS_CDRECORD | 0x84 | 대상은 쓰기 가능한 CD-ROM이며 서식이 지정되지 않은 것입니다. |
| DE_FILE_TOO_LARGE | 0x85 | 작업에 관련된 파일이 대상 미디어 또는 파일 시스템에 비해 너무 큽습니다. |
| DE_SRC_IS_CDROM | 0x86 | 원본은 읽기 전용 CD-ROM이며 형식이 지정되지 않은 것일 수 있습니다. |
| DE_SRC_IS_DVD | 0x87 | 소스는 읽기 전용 DVD이며 서식이 지정되지 않은 것일 수 있습니다. |
| DE_SRC_IS_CDRECORD | 0x88 | 원본은 쓰기 가능한 CD-ROM이며 형식이 지정되지 않은 것일 수 있습니다. |
| DE_ERROR_MAX | 0xB7 | 작업 중에 MAX_PATH 초과되었습니다. |
| 0x402 | 알 수 없는 오류가 발생했습니다. 이는 일반적으로 원본 또는 대상의 잘못된 경로 때문입니다. 이 오류는 Windows Vista 이상에서는 발생하지 않습니다. | |
| ERRORONDEST | 0x10000 | 대상에서 지정되지 않은 오류가 발생했습니다. |
| DE_ROOTDIR | ERRORONDEST | 0x10074 | 대상은 루트 디렉터리이며 이름을 바꿀 수 없습니다. |
설명
이 함수에는 정규화된 경로 이름을 사용해야 합니다. 상대 경로 이름과 함께 사용하는 것은 스레드로부터 안전하지 않습니다.
두 가지 예외를 제외하고 SHFileOperation 을 사용하여 네트워크 경로를 지정하여 로컬 드라이브에서 원격 컴퓨터로 특수 폴더를 이동할 수 없습니다. 예외는 내 문서 (CSIDL_PERSONAL, CSIDL_DOCUMENTS) 및 내 사진 폴더(CSIDL_MYPICTURES)입니다.
파일을 삭제하는 데 사용되는 경우 lpFileOp에서 가리키는 SHFILEOPSTRUCT 구조체의 fFlags 멤버에서 FOF_ALLOWUNDO 플래그를 설정하지 않는 한 SHFileOperation은 파일을 영구적으로 삭제합니다. 해당 플래그를 설정하면 파일이 휴지통으로 전송됩니다. 파일을 삭제하고 휴지통에 배치되지 않도록 하려면 DeleteFile을 사용합니다.
복사 콜백 처리기가 노출되고 등록된 경우 lpFileOp에서 가리키는 구조체의 fFlags 멤버에 FOF_NOCONFIRMATION 같은 플래그를 설정하지 않는 한 SHFileOperation은 이를 호출합니다. 복사 콜백 처리기 구현에 대한 자세한 내용은 ICopyHook::CopyCallback 을 참조하세요.
lpFileOp에서 FOF_NORECURSION 플래그를 설정하지 않는 한 파일 삭제는 재귀적입니다.
파일 연결
Windows 2000 이상에서는 HTML 파일을 GIF(그래픽 교환 형식) 이미지 또는 스타일시트와 같은 관련 파일이 포함된 폴더에 연결할 수 있습니다. 파일 연결을 사용하도록 설정하면 HTML 파일을 이동하거나 복사할 때 연결된 폴더와 모든 파일도 이동되거나 복사됩니다. 반대로 관련 파일을 사용하여 폴더를 이동하면 HTML 파일도 이동됩니다.HTML 파일에는 .htm 또는 .html 확장명이 있어야 합니다. 포함된 폴더를 HTML 파일과 동일한 폴더에 배치하여 관련 파일에 대한 연결을 만듭니다. 연결된 파일이 포함된 폴더의 이름은 HTML 파일의 이름과 같아야 하며 그 뒤에 "_files" 또는 ".files"가 와 같아야 합니다(예: "). 파일"이 작동하지 않습니다.) 여기에 예제가 제공됩니다.
- C:\Files 디렉터리(C:\Files\Test.htm)에 Test.htm이라는 파일을 만듭니다.
- C:\Files 디렉터리(C:\Files\Test.files)에 Test.files라는 새 폴더를 만듭니다.
- 폴더를 몇 개의 파일로 채웁다. 이 폴더에 있는 모든 파일은 Test.htm 연결됩니다.
- Test.htm 파일을 C:\Files2 디렉터리로 이동하거나 복사합니다.
- Test.files 디렉터리도 이제 C:\Files2 디렉터리에 있습니다.
파일 연결은 기본적으로 사용하도록 설정됩니다. 다음과 같이 REG_DWORD 항목 NoFileFolderConnection을 추가하여 사용하지 않도록 설정할 수 있습니다.
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer NoFileFolderConnection
NoFileFolderConnection을 1로 설정하면 파일 연결이 비활성화됩니다. 값이 0으로 설정되었거나 누락된 경우 파일 연결이 활성화됩니다.
지정된 파일과 연결된 파일 중 하나만 이동하려면 lpFileOp에서 가리키는 구조체의 fFlags 멤버에서 FOF_NO_CONNECTED_ELEMENTS 플래그를 설정합니다.
"MyFile_files"과 같은 이름의 폴더를 사용하여 연결을 정의하는 것은 지역화된 Windows 버전에 유효하지 않을 수 있습니다. "files"라는 용어는 로컬 언어의 해당 단어로 바꿔야 할 수 있습니다.
참고
shellapi.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 SHFileOperation을 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | shellapi.h |
| 라이브러리 | Shell32.lib |
| DLL | Shell32.dll(버전 4.0 이상) |
| API 세트 | ext-ms-win-shell-shell32-l1-2-1(Windows 10 버전 10.0.10240에 도입됨) |