SHFILEOPSTRUCTA 구조체(shellapi.h)
SHFileOperation 함수가 파일 작업을 수행하는 데 사용하는 정보를 포함합니다.
구문
typedef struct _SHFILEOPSTRUCTA {
HWND hwnd;
UINT wFunc;
PCZZSTR pFrom;
PCZZSTR pTo;
FILEOP_FLAGS fFlags;
BOOL fAnyOperationsAborted;
LPVOID hNameMappings;
PCSTR lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;
멤버
hwnd
형식: HWND
파일 작업의 상태 대한 정보를 표시하는 대화 상자에 대한 창 핸들입니다.
wFunc
형식: UINT
수행할 작업을 나타내는 값입니다. 다음 값 중 하나입니다.
FO_COPY
pFrom 멤버에 지정된 파일을 pTo 멤버에 지정된 위치에 복사합니다.
FO_DELETE
pFrom에 지정된 파일을 삭제합니다.
FO_MOVE
pFrom에 지정된 파일을 pTo에 지정된 위치로 이동합니다.
FO_RENAME
pFrom에 지정된 파일의 이름을 바꿉니다. 이 플래그를 사용하여 단일 함수 호출을 사용하여 여러 파일의 이름을 바꿀 수 없습니다. 대신 FO_MOVE 사용합니다.
pFrom
형식: PCZZTSTR
표준 MS-DOS 와일드카드 문자(예: "*")는 파일 이름 위치에 만 허용됩니다. 문자열의 다른 곳에서 와일드카드 문자를 사용하면 예측할 수 없는 결과가 발생합니다.
이 멤버는 단일 null로 끝나는 문자열로 선언되지만 실제로는 여러 null로 구분된 파일 이름을 보유할 수 있는 버퍼입니다. 각 파일 이름은 단일 NULL 문자로 종료됩니다. 마지막 파일 이름은 버퍼의 끝을 나타내기 위해 이중 NULL 문자("\0\0")로 종료됩니다.
pTo
형식: PCZZTSTR
pFrom과 마찬가지로 pTo 멤버는 이중 null로 끝나는 문자열이기도 하며 거의 동일한 방식으로 처리됩니다. 그러나 pTo 는 다음 사양을 충족해야 합니다.
- 와일드카드 문자는 지원되지 않습니다.
- 복사 및 이동 작업은 존재하지 않는 대상 디렉터리를 지정할 수 있습니다. 이러한 경우 시스템은 이러한 디렉터리를 만들려고 시도하고 일반적으로 사용자에게 새 디렉터리를 만들 것인지 묻는 대화 상자를 표시합니다. 이 대화 상자를 표시하지 않으며 디렉터리를 자동으로 만들려면 fFlags에서 FOF_NOCONFIRMMKDIR 플래그를 설정합니다.
- 복사 및 이동 작업의 경우 fFlags 멤버가 FOF_MULTIDESTFILES 지정하는 경우 버퍼에 여러 대상 파일 이름이 포함될 수 있습니다.
- pFrom과 동일한 방식으로 pTo 문자열에 여러 이름을 압축합니다.
- 정규화된 경로를 사용합니다. 상대 경로 사용은 금지되지 않지만 예측할 수 없는 결과를 가질 수 있습니다.
fFlags
형식: FILEOP_FLAGS
파일 작업을 제어하는 플래그입니다. 이 멤버는 다음 플래그의 조합을 사용할 수 있습니다.
FOF_ALLOWUNDO
가능한 경우 실행 취소 정보를 유지합니다.
Windows Vista 이전에는 원래 작업을 수행한 동일한 프로세스에서만 작업을 실행 취소할 수 있습니다.
Windows Vista 이상 시스템에서 실행 취소의 scope 사용자 세션입니다. 사용자 세션에서 실행되는 모든 프로세스는 다른 작업을 실행 취소할 수 있습니다. 실행 취소 상태는 Explorer.exe 프로세스에서 유지되며 해당 프로세스가 실행되는 한 실행 취소 함수를 조정할 수 있습니다.
원본 파일 매개 변수에 정규화된 경로 및 파일 이름이 포함되어 있지 않으면 이 플래그는 무시됩니다.
FOF_CONFIRMMOUSE
사용되지 않습니다.
FOF_FILESONLY
와일드카드 파일 이름(.)이 지정된 경우 폴더가 아닌 파일에서만 작업을 수행합니다.
FOF_MULTIDESTFILES
pTo 멤버는 모든 원본 파일을 보관할 디렉터리가 아닌 여러 대상 파일(pFrom의 각 원본 파일에 대해 하나씩)을 지정합니다.
FOF_NOCONFIRMATION
표시되는 대화 상자에 대해 모두에 예 로 응답합니다.
FOF_NOCONFIRMMKDIR
작업을 만들어야 하는 경우 사용자에게 새 디렉터리 만들기를 확인하도록 요청하지 마세요.
FOF_NO_CONNECTED_ELEMENTS
버전 5.0. 연결된 파일을 그룹으로 이동하지 마세요. 지정된 파일만 이동합니다.
FOF_NOCOPYSECURITYATTRIBS
버전 4.71. 파일의 보안 특성을 복사하지 마세요. 대상 파일은 새 폴더의 보안 특성을 받습니다.
FOF_NOERRORUI
오류가 발생하는 경우 사용자에게 대화 상자를 표시하지 마세요.
FOF_NORECURSEREPARSE
사용되지 않습니다.
FOF_NORECURSION
로컬 디렉터리에서만 작업을 수행합니다. 기본 동작인 하위 디렉터리로 재귀적으로 작동하지 않습니다.
FOF_NO_UI
Windows Vista. 사용자에게 UI를 표시하지 않고 자동으로 작업을 수행합니다. 이는 FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.
FOF_RENAMEONCOLLISION
대상 이름을 가진 파일이 대상에 이미 있는 경우 이동, 복사 또는 이름 바꾸기 작업에서 새 이름으로 작업 중인 파일을 지정합니다.
FOF_SILENT
진행률 대화 상자를 표시하지 마세요.
FOF_SIMPLEPROGRESS
진행률 대화 상자를 표시하지만 작업 중인 개별 파일 이름은 표시하지 않습니다.
FOF_WANTMAPPINGHANDLE
FOF_RENAMEONCOLLISION 지정되고 파일 이름이 변경된 경우 이전 이름과 새 이름이 포함된 이름 매핑 개체를 hNameMappings 멤버에 할당합니다. 이 개체는 더 이상 필요하지 않은 경우 SHFreeNameMappings 를 사용하여 해제해야 합니다.
FOF_WANTNUKEWARNING
버전 5.0. 파일이 재활용되지 않고 삭제 작업 중에 영구적으로 삭제되는 경우 경고를 보냅니다. 이 플래그는 FOF_NOCONFIRMATION 부분적으로 재정의합니다.
fAnyOperationsAborted
형식: BOOL
함수가 반환될 때 파일 작업이 완료되기 전에 중단된 경우 이 멤버에는 TRUE 가 포함됩니다. 그렇지 않으면 FALSE입니다. UI를 통해 사용자가 작업을 수동으로 중단하거나 FOF_NOERRORUI 또는 FOF_NOCONFIRMATION 플래그가 설정된 경우 시스템에서 자동으로 중단될 수 있습니다.
hNameMappings
형식: LPVOID
함수가 반환되면 이 멤버는 이름이 바뀐 파일의 이전 이름과 새 이름을 포함하는 이름 매핑 개체에 대한 핸들을 포함합니다. 이 멤버는 fFlags 멤버에 FOF_WANTMAPPINGHANDLE 플래그가 포함된 경우에만 사용됩니다. 자세한 내용은 비고를 참조하세요.
lpszProgressTitle
형식: PCTSTR
진행률 대화 상자의 제목에 대한 포인터입니다. null로 끝나는 문자열입니다. 이 멤버는 fFlags 에 FOF_SIMPLEPROGRESS 플래그가 포함된 경우에만 사용됩니다.
설명
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";
// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";
종료되는 두 null 문자를 고려하려면 MAX_PATH(일반적으로 단일 종료 null 문자 포함)에 1을 더할 수 있을 만큼 큰 버퍼를 만들어야 합니다.
경로가 항상 전체 경로여야 한다는 것을 과장할 수 없습니다. pFrom 또는 pTo 멤버가 정규화되지 않은 이름인 경우 GetCurrentDirectory 및 SetCurrentDirectory 함수에서 관리하는 전역 현재 드라이브 및 디렉터리 설정에서 현재 디렉터리를 가져옵니다.
전체 경로를 제공하지 않으면 다음과 같은 사실이 관련됩니다.
- 파일 이름 앞에 경로가 없으면 이 파일이 현재 디렉터리의 루트에 있음을 SHFileOperation 에 나타내지 않습니다.
- PATH 환경 변수는 SHFileOperation 에서 유효한 경로를 확인하는 데 사용되지 않습니다.
- SHFileOperation 은 실행을 시작할 때 현재 디렉터리인 디렉터리를 사용하기 위해 사용할 수 없습니다. 현재 디렉터리로 표시되는 디렉터리가 프로세스 전체이며 작업이 실행되는 동안 다른 스레드에서 변경할 수 있습니다. 이 경우 SHFileOperation 의 결과를 예측할 수 없습니다.
pFrom이 전체 경로가 없는 파일 이름으로 설정된 경우 FO_DELETE 사용하여 파일을 삭제해도 FOF_ALLOWUNDO 플래그가 설정된 경우에도 휴지통으로 이동되지 않습니다. 휴지통에 파일을 삭제하려면 전체 경로를 제공해야 합니다.
"\?"라는 접두사로 지정된 경로에서 SHFileOperation이 실패합니다.
이 구조체에는 ANSI 버전(SHFILEOPSTRUCTA)과 유니코드 버전(SHFILEOPSTRUCTW)의 두 가지 버전이 있습니다. 유니코드 버전은 ANSI 문자열(LPCWSTR) 대신 LPCWSTR(와이드 문자열)이 사용된다는 점을 제외하고 ANSI 버전과 동일합니다. Windows 98 이전 버전에서는 ANSI 버전만 지원됩니다. Microsoft Windows NT 4.0 이상에서는 이 구조체의 ANSI 및 유니코드 버전이 모두 지원됩니다. SHFILEOPSTRUCTW 및 SHFILEOPTSTRUCTA는 직접 사용하면 안 됩니다. 적절한 구조는 애플리케이션이 ANSI 또는 유니코드용으로 컴파일되는지 여부에 따라 미리 컴파일러에 의해 SHFILEOPSTRUCT 로 다시 정의됩니다.
SHNAMEMAPPING 에는 유사한 ANSI 및 유니코드 버전이 있습니다. ANSI 애플리케이션의 경우 hNameMappings 는 int 를 가리킨 다음 ANSI SHNAMEMAPPING 구조체의 배열을 가리킵니다. 유니코드 애플리케이션의 경우 hNameMappings 는 int 를 가리킨 다음 유니코드 SHNAMEMAPPING 구조의 배열을 가리킵니다. 그러나 Microsoft Windows NT 4.0 이상에서 SHFileOperation은 항상SHNAMEMAPPING 구조체의 유니코드 집합에 대한 핸들을 반환합니다. 모든 버전의 Windows에서 애플리케이션을 작동하려면 애플리케이션이 조건부 코드를 사용하여 이름 매핑을 처리해야 합니다. 예를 들면 다음과 같습니다.
x = SHFileOperation(&shop);
if (fWin9x)
HandleAnsiNameMappings(shop.hNameMappings);
else
HandleUnicodeNameMappings(shop.hNameMappings);
hNameMappings를 멤버가 UINT 값인 구조체에 대한 포인터로 처리한 다음, 선언에서 볼 수 있듯이 SHNAMEMAPPING 구조체의 배열에 대한 포인터로 처리합니다.
struct HANDLETOMAPPINGS
{
UINT uNumberOfMappings; // Number of mappings in the array.
LPSHNAMEMAPPING lpSHNameMapping; // Pointer to the array of mappings.
};
UINT 값은 배열의 SHNAMEMAPPING 구조체 수를 나타냅니다. 각 SHNAMEMAPPING 구조체에는 이름이 바뀐 파일 중 하나에 대한 이전 경로와 새 경로가 포함됩니다.
참고
shellapi.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 SHFILEOPSTRUCT를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 머리글 | shellapi.h |
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기