SHGetKnownFolderItem 함수(shlobj_core.h)

아티클
08/08/2024

알려진 폴더를 나타내는 IShellItem 개체를 검색합니다.

구문

HRESULT SHGetKnownFolderItem(
  [in]  REFKNOWNFOLDERID  rfid,
  [in]  KNOWN_FOLDER_FLAG flags,
  [in]  HANDLE            hToken,
  [in]  REFIID            riid,
  [out] void              **ppv
);

매개 변수

[in] rfid

형식: REFKNOWNFOLDERID

항목을 포함하는 폴더를 식별하는 GUID인 KNOWNFOLDERID에 대한 참조입니다.

[in] flags

형식: KNOWN_FOLDER_FLAG

알려진 폴더 IShellItem 검색에 사용되는 특수 옵션을 지정하는 플래그입니다. 이 값은 KF_FLAG_DEFAULT 수 있습니다. 그렇지 않으면 하나 이상의 KNOWN_FOLDER_FLAG 값입니다.

[in] hToken

형식: HANDLE

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

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

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

[in] riid

형식: REFIID

일반적으로 IID_IShellItem 또는 IID_IShellItem2 항목을 나타내는 인터페이스의 IID에 대한 참조입니다.

[out] ppv

형식: void**

이 메서드가 반환되면 는 riid에서 요청된 인터페이스 포인터를 포함합니다.

반환 값

형식: HRESULT

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

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

설명

이 함수의 호출자에게는 관리자 권한이 있어야 합니다. 공용 알려진 폴더에서 이 함수를 호출하려면 호출자에게 관리자 권한이 있어야 합니다. 사용자별 알려진 폴더의 경우 호출자에게는 사용자 권한만 필요합니다.

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

이 함수는 KF_CATEGORY_FIXED 및 KF_CATEGORY_VIRTUAL 형식의 폴더에서 호출할 수 없습니다.

KF_CATEGORY_COMMON 형식의 폴더에서 이 함수를 호출하려면 호출 애플리케이션이 관리자 권한으로 실행되어야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 7 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 R2 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	shlobj_core.h(Shlobj.h 포함)
라이브러리	Shell32.lib
DLL	Shell32.dll(버전 6.1 이상)
API 세트	ext-ms-win-shell-shell32-l1-2-1(Windows 10 버전 10.0.10240에 도입됨)