SHGetKnownFolderItem 函式（shlobj_core.h）

擷取一個代表已知資料夾的 IShellItem 物件。

語法

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

Parameters

[in] rfid

類型： REFKNOWNFOLDERID

KNOWNFOLDERID 的參考，這是識別包含專案之資料夾的 GUID。

[in] flags

類型： KNOWN_FOLDER_FLAG

標示用於擷取已知資料夾 IShellItem 時使用的特殊選項。 這個數值可以 KF_FLAG_DEFAULT;否則，則是 KNOWN_FOLDER_FLAG 值中的一個或多個。

[in] hToken

類型： 手柄

用來代表特定使用者的 存取權杖 。 此參數通常設定為 NULL，在這種情況下，函數會嘗試存取目前使用者的資料夾實例。 不過，您可能需要為那些可以有多個使用者但被視為屬於單一使用者的資料夾指派 hToken 值。 此類型最常用的資料夾是 Documents。

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

指派 hToken 參數值 -1 表示預設使用者。 這可讓 SHSetKnownFolderPath 的用戶端設定預設使用者的資料夾位置 （，例如 桌面 資料夾） 。 建立任何新使用者帳戶時，會複製預設使用者使用者設定檔，並包含特殊資料夾，例如 「文件」 和 「桌面」。 新增至「預設使用者」資料夾的任何項目也會顯示在任何新的使用者帳戶中。 請注意，存取預設使用者資料夾需要管理員權限。

[in] riid

類型： REFIID

指介面的 IID，代表該物品，通常是 IID_IShellItem 或 IID_IShellItem2。

[out] ppv

類型： 無效**

當這個方法傳回時，包含 riid 中要求的介面指標。

返回值

類型：HRESULT

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

備註

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

某些已知資料夾 （例如 Documents 資料夾） 是每個使用者的。 每個使用者的 [文件] 資料夾都有不同的路徑。 如果 hToken 為 Null，API 會嘗試存取呼叫應用程式的資料夾實例，也就是目前使用者的實例。 如果 hToken 是有效的使用者權杖，API 會嘗試使用此權杖模擬使用者，並嘗試存取該使用者的執行個體。

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

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

要求

另請參閱

IKnownFolder：：GetPath

IKnownFolderManager：：重定向

已知資料夾範例

SHCreateItemInKnown資料夾

SHGetKnownFolderIDList

SHGetKnownFolderPath