SHGetKnownFolderPath 函式 (shlobj_core.h)

  • 發行項

擷取資料夾 KNOWNFOLDERID所識別之已知資料夾的完整路徑。

語法

HRESULT SHGetKnownFolderPath(
  [in]           REFKNOWNFOLDERID rfid,
  [in]           DWORD            dwFlags,
  [in, optional] HANDLE           hToken,
  [out]          PWSTR            *ppszPath
);

參數

[in] rfid

類型： REFKNOWNFOLDERID

KNOWNFOLDERID的參考，可識別資料夾。

[in] dwFlags

類型： DWORD

指定特殊擷取選項的旗標。 此值可以是 0;否則，一或多個 KNOWN_FOLDER_FLAG 值。

[in, optional] hToken

類型： HANDLE

代表特定使用者的 存取權杖 。 如果此參數是 Null，這是最常見的用法，函式會要求目前使用者的已知資料夾。

傳遞該使用者的 hToken ，以要求特定使用者的資料夾。 這通常是在具有足夠許可權的服務內容中完成，以擷取指定使用者的權杖。 該權杖必須以 TOKEN_QUERY 和 TOKEN_IMPERSONATE 許可權開啟。 在某些情況下，您也需要包含 TOKEN_DUPLICATE。 除了傳遞使用者的 hToken之外，還必須掛接該特定使用者的登錄區。 如需存取控制問題的進一步討論，請參閱存取控制。

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

[out] ppszPath

類型： PWSTR*

當這個方法傳回時，會包含指定已知資料夾路徑之 Null 終止 Unicode 字串之指標的位址。 呼叫進程會負責在 呼叫 CoTaskMemFree不再需要此資源之後釋放此資源，無論 SHGetKnownFolderPath 是否成功。 傳回的路徑不包含尾端反斜線。 例如，會傳回 「C：\Users」，而不是 「C：\Users\」。

傳回值

類型： HRESULT

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

傳回碼 描述
E_FAIL
 除此之外，這個值可能表示 ( 的 KNOWNFOLDERID 參考了 KNOWNFOLDERID ，例如標示為 KF_CATEGORY_VIRTUAL) 的資料夾。
E_INVALIDARG
 除此之外，這個值可能表示 其會 參考系統上不存在的 KNOWNFOLDERID 。 並非所有 KNOWNFOLDERID 值都存在於所有系統上。 使用 IKnownFolderManager：：GetFolderIds 來擷取目前系統的 KNOWNFOLDERID 值集合。

備註

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

規格需求

   
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 shlobj_core.h (包含 Shlobj.h)
Dll Shell32.dll (6.0.6000 版或更新版本)

另請參閱

IKnownFolder：：GetPath

已知資料夾範例

SHGetKnownFolderIDList

SHSetKnownFolderPath