SHGetKnownFolderIDList 함수(shlobj_core.h)

  • 아티클

알려진 폴더의 경로를 ITEMIDLIST 구조체로 검색합니다.

구문

HRESULT SHGetKnownFolderIDList(
  [in]  REFKNOWNFOLDERID rfid,
  [in]  DWORD            dwFlags,
  [in]  HANDLE           hToken,
  [out] PIDLIST_ABSOLUTE *ppidl
);

매개 변수

[in] rfid

형식: REFKNOWNFOLDERID

폴더를 식별하는 KNOWNFOLDERID 에 대한 참조입니다. 알려진 폴더 ID와 연결된 폴더가 특정 시스템에 없을 수 있습니다.

[in] dwFlags

형식:DWORD

특수 검색 옵션을 지정하는 플래그입니다. 이 값은 0일 수 있습니다. 그렇지 않으면 KNOWN_FOLDER_FLAG 값 중 하나 이상입니다.

[in] hToken

형식: HANDLE

특정 사용자를 나타내는 데 사용되는 액세스 토큰 입니다. 이 매개 변수는 일반적으로 NULL로 설정되며, 이 경우 함수는 폴더의 현재 사용자 instance 액세스하려고 합니다. 그러나 여러 사용자가 있을 수 있지만 단일 사용자에 속하는 것으로 처리되는 폴더에 대해 hToken 에 값을 할당해야 할 수 있습니다. 이 유형의 가장 일반적으로 사용되는 폴더는 Documents입니다.

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

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

[out] ppidl

형식: PIDLIST_ABSOLUTE*

이 메서드가 반환되면 폴더의 PIDL에 대한 포인터가 포함됩니다. 이 매개 변수는 초기화되지 않은 상태로 전달됩니다. 호출자는 ILFree를 호출하여 더 이상 필요하지 않은 경우 반환된 PIDL을 해제할 책임이 있습니다.

반환 값

형식: HRESULT

성공하면 S_OK 반환하고, 그렇지 않으면 다음을 포함하여 오류 값을 반환합니다.

반환 코드 설명
E_INVALIDARG
 무엇보다도 이 값은 rfid 매개 변수가 시스템에 없는 KNOWNFOLDERID 를 참조함을 나타낼 수 있습니다. 모든 KNOWNFOLDERID 값이 모든 시스템에 있는 것은 아닙니다. IKnownFolderManager::GetFolderIds를 사용하여 현재 시스템에 대한 KNOWNFOLDERID 값 집합을 검색합니다.

설명

이 함수는 SHGetFolderLocation을 대체합니다. 이전 함수는 이제 SHGetKnownFolderIDList에 대한 래퍼일 뿐입니다.

이 함수를 사용하는 호출자에게는 사용자 이상의 권한이 있어야 합니다.

일부 알려진 폴더(예: Documents 폴더)는 사용자 단위입니다. 각 사용자에게는 Documents 폴더에 대한 다른 경로가 있습니다. hToken이 NULL인 경우 API는 폴더의 현재 사용자 instance 액세스하려고 합니다. hToken이 유효한 사용자 토큰인 경우 API는 이 토큰을 사용하여 사용자를 가장하고 해당 사용자의 폴더 instance 액세스하려고 시도합니다.

요구 사항

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

추가 정보

IKnownFolder::GetPath

알려진 폴더 샘플

SHGetKnownFolderPath

SHSetKnownFolderPath