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

类型：句柄

用于表示特定用户的访问令牌。此参数通常设置为 NULL，在这种情况下，函数会尝试访问当前用户的文件夹实例。但是，对于可以有多个用户但被视为属于单个用户的文件夹，可能需要为 hToken 分配一个值。此类型最常用的文件夹是 Documents。

当 hToken 为非 null 时，调用应用程序负责正确模拟。它必须对特定用户具有适当的安全权限，包括TOKEN_QUERY和TOKEN_IMPERSONATE，并且当前必须装载用户的注册表配置单元。有关访问控制问题的进一步讨论，请参阅访问控制。

为 hToken 参数分配值 -1 表示默认用户。这允许 SHSetKnownFolderPath 的客户端设置文件夹位置 (，例如默认用户的桌面文件夹) 。创建任何新用户帐户时，默认用户用户配置文件将重复，并包含文档和桌面等特殊文件夹。添加到“默认用户”文件夹的任何项目也会显示在任何新用户帐户中。请注意，访问“默认用户”文件夹需要管理员权限。

[in] riid

类型： REFIID

对表示项的接口的 IID 的引用，通常IID_IShellItem或IID_IShellItem2。

[out] ppv

类型： void**

此方法返回时，包含 riid 中请求的接口指针。

返回值

类型： HRESULT

如果成功，则返回S_OK，否则返回错误值，包括：

返回代码	说明
E_INVALIDARG	除其他事项外，此值可以指示该 rf 参数引用系统上不存在的 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)
Library	Shell32.lib
DLL	Shell32.dll (版本 6.1 或更高版本)
API 集	Windows 10版本 10.0.10240 中引入的 ext-ms-win-shell-shell32-l1-2-1 ()