SHGetFolderPathA 함수(shlobj_core.h)

더 이상 사용되지 않습니다. CSIDL 값으로 식별되는 폴더의 경로를 가져옵니다.

참고 Windows Vista를 기준으로 이 함수는 SHGetKnownFolderPath에 대한 래퍼일 뿐입니다. CSIDL 값은 연결된 KNOWNFOLDERID 로 변환된 다음 SHGetKnownFolderPath 가 호출됩니다. 새 애플리케이션은 이전 버전과의 호환성을 위해서만 지원되는 이전 CSIDL 시스템 대신 알려진 폴더 시스템을 사용해야 합니다.

 

구문

SHFOLDERAPI SHGetFolderPathA(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPSTR  pszPath
);

매개 변수

[in] hwnd

형식: HWND

예약되어 있습니다.

[in] csidl

형식: int

경로를 검색할 폴더를 식별하는 CSIDL 값입니다. 실제 폴더만 유효합니다. 가상 폴더를 지정하면 이 함수가 실패합니다. 폴더의 CSIDL 을 CSIDL_FLAG_CREATE 결합하여 폴더를 강제로 만들 수 있습니다.

[in] hToken

형식: HANDLE

특정 사용자를 나타내는 데 사용할 수 있는 액세스 토큰 입니다.

Microsoft Windows 2000 이하: 항상 이 매개 변수를 NULL로 설정합니다.

Windows XP 이상: 이 매개 변수는 일반적으로 NULL로 설정되지만 여러 사용자가 있을 수 있지만 단일 사용자에 속하는 것으로 처리되는 폴더에 대해 NULL 이 아닌 값을 hToken 에 할당해야 할 수 있습니다. 이 유형의 가장 일반적으로 사용되는 폴더는 Documents입니다.

호출 프로세스는 hToken 이 NULL이 아닌 경우 올바른 가장을 담당합니다. 호출 프로세스에는 TOKEN_QUERY 및 TOKEN_IMPERSONATE 포함하여 특정 사용자에 대한 적절한 보안 권한이 있어야 하며 사용자의 레지스트리 하이브가 현재 탑재되어 있어야 합니다. 액세스 제어 문제에 대한 자세한 내용은 Access Control 참조하세요.

hToken 매개 변수에 -1 값을 할당하면 기본 사용자가 표시됩니다. 이렇게 하면 SHGetFolderPath 의 클라이언트가 기본 사용자에 대한 폴더 위치(예: 데스크톱 폴더)를 찾을 수 있습니다. 기본 사용자 프로필은 새 사용자 계정을 만들 때 중복되며 내 문서 및 데스크톱과 같은 특수 폴더를 포함합니다. 기본 사용자 폴더에 추가된 모든 항목도 새 사용자 계정에 표시됩니다.

[in] dwFlags

형식:DWORD

반환할 경로를 지정하는 플래그입니다. 이 값은 KNOWNFOLDERID (또는 CSIDL)와 연결된 폴더를 사용자 또는 관리자가 언어 간에 이동, 이름 바꾸기, 리디렉션 또는 로밍할 수 있는 경우에 사용됩니다.

SHGetFolderPath의 근간이 되는 알려진 폴더 시스템을 사용하면 사용자 또는 관리자가 알려진 폴더를 요구 사항에 맞는 위치로 리디렉션할 수 있습니다. 이 작업은 SHGFP_TYPE_CURRENT 플래그와 연결된 폴더의 "현재" 값을 설정하는 IKnownFolderManager::Redirect를 호출하여 수행됩니다.

사용자 또는 관리자가 다른 곳에서 리디렉션하지 않은 경우 폴더의 위치인 폴더의 기본값은 SHGFP_TYPE_DEFAULT 플래그를 지정하여 검색됩니다. 이 값은 알려진 폴더에 대한 "기본값 복원" 기능을 구현하는 데 사용할 수 있습니다.

예를 들어 FOLDERID_Music(CSIDL_MYMUSIC )의 기본 값(SHGFP_TYPE_DEFAULT)은 "C:\Users\user name\Music"입니다. 폴더가 리디렉션된 경우 현재 값(SHGFP_TYPE_CURRENT)은 "D:\Music"일 수 있습니다. 폴더가 리디렉션되지 않은 경우 SHGFP_TYPE_DEFAULT SHGFP_TYPE_CURRENT 동일한 경로를 검색합니다.

SHGFP_TYPE_CURRENT

폴더의 현재 경로를 검색합니다.

SHGFP_TYPE_DEFAULT

폴더의 기본 경로를 검색합니다.

[out] pszPath

형식: LPTSTR

경로를 수신할 길이 MAX_PATH null로 끝나는 문자열에 대한 포인터입니다. 오류가 발생하거나 S_FALSE 반환되면 이 문자열은 비어 있습니다. 반환된 경로에는 후행 백슬래시가 포함되지 않습니다. 예를 들어 "C:\Users"는 "C:\Users\" 대신 반환됩니다.

반환 값

형식: HRESULT

이 함수가 성공하면 S_OK 반환합니다. 그러지 않으면 HRESULT 오류 코드를 반환합니다.

설명

이 함수는 SHGetSpecialFolderPath의 상위 집합입니다.

다음을 포함하여 일부 CSIDL 값만 지원됩니다.

• CSIDL_ADMINTOOLS
• CSIDL_APPDATA
• CSIDL_COMMON_ADMINTOOLS
• CSIDL_COMMON_APPDATA
• CSIDL_COMMON_DOCUMENTS
• CSIDL_COOKIES
• CSIDL_FLAG_CREATE
• CSIDL_FLAG_DONT_VERIFY
• CSIDL_HISTORY
• CSIDL_INTERNET_CACHE
• CSIDL_LOCAL_APPDATA
• CSIDL_MYPICTURES
• CSIDL_PERSONAL
• CSIDL_PROGRAM_FILES
• CSIDL_PROGRAM_FILES_COMMON
• CSIDL_SYSTEM
• CSIDL_WINDOWS

예제

다음 코드 예제에서는 SHGetFolderPath 를 사용하여 폴더를 찾거나 만든 다음, 폴더에 파일을 만듭니다.

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

요구 사항

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

추가 정보

IKnownFolder::GetPath