SHSetKnownFolderPath 函数 (shlobj_core.h)

项目
08/26/2023

将已知文件夹重定向到新位置。

语法

HRESULT SHSetKnownFolderPath(
  [in] REFKNOWNFOLDERID rfid,
  [in] DWORD            dwFlags,
  [in] HANDLE           hToken,
  [in] PCWSTR           pszPath
);

参数

[in] rfid

类型： REFKNOWNFOLDERID

标识已知文件夹的 GUID 。

[in] dwFlags

类型：DWORD

0 或以下值。

KF_FLAG_DONT_UNEXPAND

如果设置了此标志， 则 pszPath 引用的路径部分可能由环境字符串（如 %USERPROFILE%）表示。

[in] hToken

类型：句柄

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

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

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

[in] pszPath

类型： PCWSTR

指向文件夹的新路径的指针。这是长度为 MAX_PATH 的以 null 结尾的 Unicode 字符串。此路径的长度不能为零。

返回值

类型： HRESULT

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

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

注解

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

此函数的调用方必须具有管理员权限。若要在公共已知文件夹上调用此函数，调用方必须具有管理员权限。对于每用户已知文件夹，调用方只需要用户权限。

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

无法在 KF_CATEGORY_FIXED 和 KF_CATEGORY_VIRTUAL类型的文件夹上调用此函数。

若要在 KF_CATEGORY_COMMON 类型的文件夹上调用此函数，调用应用程序必须以提升的权限运行。

要求

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