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，在此情況下，函式會嘗試存取目前使用者的資料夾實例。不過，您可能需要為可有多個使用者但被視為屬於單一用戶的資料夾，將值指派給 hToken 。此類型最常使用的資料夾是 Documents。

當 hToken 為非 Null 時，呼叫的應用程式會負責正確的模擬。它必須具有特定用戶的適當安全性許可權，包括TOKEN_QUERY和TOKEN_IMPERSONATE，而且目前必須掛接使用者的登錄區。如需訪問控制問題的進一步討論，請參閱存取控制。

將 hToken 參數指派為 -1 的值表示預設使用者。這可讓 SHSetKnownFolderPath 的用戶端設定資料夾位置 (，例如預設使用者的 Desktop 資料夾) 。建立任何新的使用者帳戶時，預設使用者配置檔會重複，並包含檔與桌面等特殊資料夾。新增至 [預設使用者] 資料夾的任何專案也會出現在任何新的用戶帳戶中。請注意，存取預設使用者資料夾需要系統管理員許可權。

[in] pszPath

類型： PCWSTR

資料夾新路徑的指標。這是長度為 null 的 Unicode 字串MAX_PATH。這個路徑不能是零長度。

傳回值

類型： HRESULT

如果成功，則傳回S_OK，否則傳回錯誤值，包括下列專案：

傳回碼	Description
E_INVALIDARG	此外，這個值也可以指出，此標識符會參考系統上不存在的 KNOWNFOLDERID 。並非所有 KNOWNFOLDERID 值都存在於所有系統上。使用 IKnownFolderManager：：GetFolderIds 來擷取目前系統的 KNOWNFOLDERID 值集。

備註

此函式會取代 SHSetFolderPath。該較舊的函式現在只是 SHSetKnownFolderPath 的包裝函式。

此函式的呼叫端必須具有系統管理員許可權。若要在公用資料夾上呼叫此函式，呼叫端必須具有系統管理員許可權。針對每位使用者的已知資料夾，呼叫端只需要用戶許可權。

例如，某些已知的資料夾，例如 Documents 資料夾是每個使用者。每位使用者都有其 Documents 資料夾的不同路徑。如果 hToken 為 NULL，API 會嘗試存取呼叫端應用程式的資料夾實例，也就是目前使用者的實例。如果 hToken 是有效的使用者令牌，API 會嘗試使用此令牌模擬使用者，並嘗試存取該用戶的實例。

無法在類型為 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 版或更新版本)