SHGetKnownFolderItem 函式 (shlobj_core.h)

發行項
03/02/2024

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

語法

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

參數

[in] rfid

類型： REFKNOWNFOLDERID

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

[in] flags

類型： KNOWN_FOLDER_FLAG

旗標，指定擷取已知資料夾 IShellItem 時所使用的特殊選項。此值可以是 KF_FLAG_DEFAULT;否則，一或多個 KNOWN_FOLDER_FLAG 值。

[in] hToken

類型： HANDLE

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

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

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

[in] riid

類型： REFIID

代表專案的介面 IID 參考，通常IID_IShellItem或IID_IShellItem2。

[out] ppv

類型： void**

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

傳回值

類型： HRESULT

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

傳回碼	Description
E_INVALIDARG	除此之外，這個值可能表示其會參考系統上不存在的 KNOWNFOLDERID 。並非所有 KNOWNFOLDERID 值都存在於所有系統上。使用 IKnownFolderManager：：GetFolderIds 來擷取目前系統的 KNOWNFOLDERID 值集合。

備註

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

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

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

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

規格需求

需求	值
最低支援的用戶端	Windows 7 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 R2 [僅限桌面應用程式]
目標平台	Windows
標頭	shlobj_core.h (包含 Shlobj.h)
程式庫	Shell32.lib
Dll	Shell32.dll (6.1 版或更新版本)
API 集合	ext-ms-win-shell-shell32-l1-2-1 (在 Windows 10 10.0.10240 版中引進)