SHGetKnownFolderIDList 函式 (shlobj_core.h)

  • 發行項

擷取名為 ITEMIDLIST 結構的已知資料夾路徑。

語法

HRESULT SHGetKnownFolderIDList(
  [in]  REFKNOWNFOLDERID rfid,
  [in]  DWORD            dwFlags,
  [in]  HANDLE           hToken,
  [out] PIDLIST_ABSOLUTE *ppidl
);

參數

[in] rfid

類型： REFKNOWNFOLDERID

識別資料夾之 KNOWNFOLDERID 的參考。 與已知資料夾標識符相關聯的資料夾可能不存在於特定系統上。

[in] dwFlags

類型： DWORD

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

[in] hToken

類型： HANDLE

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

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

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

[out] ppidl

類型： PIDLIST_ABSOLUTE*

當這個方法傳回時，會包含資料夾 PIDL 的指標。 這個參數會以未初始化的狀態傳遞。 呼叫端負責在呼叫 ILFree 不再需要時釋放傳回的 PIDL。

傳回值

類型： HRESULT

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

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

備註

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

使用此函式的呼叫端至少必須具有用戶許可權。

例如，某些已知的資料夾， [檔案 ] 資料夾是每個使用者。 每個使用者都有 文件資料夾的不同 路徑。 如果 hToken 為 NULL，API 會嘗試存取目前使用者的資料夾實例。 如果 hToken 是有效的使用者令牌，API 會嘗試使用此令牌模擬使用者，並嘗試存取該使用者的資料夾實例。

規格需求

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

另請參閱

IKnownFolder：：GetPath

已知資料夾範例

SHGetKnownFolderPath

SHSetKnownFolderPath