SHGetKnownFolderIDList 函数 (shlobj_core.h)

  • 项目

检索已知文件夹的路径作为 ITEMIDLIST 结构。

语法

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

参数

[in] rfid

类型： REFKNOWNFOLDERID

对标识文件夹的 KNOWNFOLDERID 的引用。 特定系统上可能不存在与已知文件夹 ID 关联的文件夹。

[in] dwFlags

类型：DWORD

指定特殊检索选项的标志。 此值可以为 0;否则，它是 一个或多个KNOWN_FOLDER_FLAG 值。

[in] hToken

类型： 句柄

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

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

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

[out] ppidl

类型： PIDLIST_ABSOLUTE*

此方法返回时，包含指向文件夹的 PIDL 的指针。 此参数未经初始化即被传递。 调用方负责通过调用 ILFree 不再需要返回的 PIDL 时释放该 PIDL。

返回值

类型： HRESULT

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

返回代码 说明
E_INVALIDARG
 除其他事项外，此值可以指示 该 rf 参数引用系统上不存在的 KNOWNFOLDERID 。 并非所有 KNOWNFOLDERID 值都存在于所有系统上。 使用 IKnownFolderManager：：GetFolderIds 检索当前系统的 KNOWNFOLDERID 值集。

注解

此函数替换 SHGetFolderLocation。 该旧函数现在只是 SHGetKnownFolderIDList 的包装器。

使用此函数的调用方必须至少具有用户权限。

某些已知文件夹（例如 Documents 文件夹）是每个用户的。 每个用户对 Documents 文件夹具有不同的路径。 如果 hToken 为 NULL，则 API 会尝试访问当前用户的文件夹实例。 如果 hToken 是有效的用户令牌，则 API 会尝试使用此令牌模拟用户，并尝试访问该用户的文件夹实例。

要求

要求 值
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 shlobj_core.h (包括 Shlobj.h)
Library Shell32.lib
DLL Shell32.dll (版本 6.0.6000 或更高版本)

另请参阅

IKnownFolder：：GetPath

已知文件夹示例

SHGetKnownFolderPath

SHSetKnownFolderPath