SHSetKnownFolderPath 函式 (shlobj_core.h)

將已知資料夾重新導向至新的位置。

語法

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，否則傳回錯誤值，包括下列專案：

備註

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

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

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

無法在 類型為 KF_CATEGORY_FIXED 和 KF_CATEGORY_VIRTUAL 的資料夾上呼叫此函式。

若要在類型 為 KF_CATEGORY_COMMON 的資料夾上呼叫此函式，呼叫的應用程式必須以提高的許可權執行。

規格需求

另請參閱

IKnownFolder：：GetPath

IKnownFolder：：SetPath

IKnownFolderManager：：Redirect

已知資料夾範例

SHGetKnownFolderIDList

SHGetKnownFolderPath