다음을 통해 공유


SHFileOperationA 함수(shellapi.h)

파일 시스템 개체를 복사, 이동, 이름 바꾸기 또는 삭제합니다. 이 함수는 Windows Vista에서 IFileOperation으로 대체되었습니다.

구문

int SHFileOperationA(
  [in, out] LPSHFILEOPSTRUCTA lpFileOp
);

매개 변수

[in, out] lpFileOp

형식: LPSHFILEOPSTRUCT

이 함수가 지정된 작업을 수행하는 데 필요한 정보를 포함하는 SHFILEOPSTRUCT 구조체에 대한 포인터입니다. 이 매개 변수는 NULL이 아닌 유효한 값을 포함해야 합니다. 값의 유효성을 검사할 책임이 있습니다. 유효성을 검사하지 않으면 예기치 않은 결과가 발생합니다.

반환 값

형식: int

성공하면 0을 반환합니다. 그렇지 않으면 0이 아닌 값입니다. 애플리케이션은 일반적으로 0 또는 0이 아닌 경우 단순히 검사 합니다.

SHFILEOPSTRUCTfAnyOperationsAborted 멤버 값을 검사하는 것이 좋습니다. 사용자가 작업을 취소하는 경우 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"가 와 같아야 합니다(예: "). 파일"이 작동하지 않습니다.) 여기에 예제가 제공됩니다.

  1. C:\Files 디렉터리(C:\Files\Test.htm)에 Test.htm이라는 파일을 만듭니다.
  2. C:\Files 디렉터리(C:\Files\Test.files)에 Test.files라는 새 폴더를 만듭니다.
  3. 폴더를 몇 개의 파일로 채웁다. 이 폴더에 있는 모든 파일은 Test.htm 연결됩니다.
  4. Test.htm 파일을 C:\Files2 디렉터리로 이동하거나 복사합니다.
  5. 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에 도입됨)