SHSetKnownFolderPath 함수(shlobj_core.h)

아티클
03/02/2024

알려진 폴더를 새 위치로 리디렉션합니다.

구문

HRESULT SHSetKnownFolderPath(
  [in] REFKNOWNFOLDERID rfid,
  [in] DWORD            dwFlags,
  [in] HANDLE           hToken,
  [in] PCWSTR           pszPath
);

매개 변수

[in] rfid

형식: REFKNOWNFOLDERID

알려진 폴더를 식별하는 GUID 입니다.

[in] dwFlags

형식:DWORD

0 또는 다음 값입니다.

KF_FLAG_DONT_UNEXPAND

이 플래그를 설정하면 pszPath 에서 참조하는 경로의 일부가 와 같은 %USERPROFILE%환경 문자열로 표시될 수 있습니다.

[in] hToken

형식: HANDLE

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

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

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

[in] pszPath

형식: PCWSTR

폴더의 새 경로에 대한 포인터입니다. 길이 MAX_PATH null로 끝나는 유니코드 문자열입니다. 이 경로는 길이가 0일 수 없습니다.

반환 값

형식: HRESULT

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

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

설명

이 함수는 SHSetFolderPath를 대체합니다. 이전 함수는 이제 SHSetKnownFolderPath에 대한 래퍼일 뿐입니다.

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

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

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

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

요구 사항

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