SHSetKnownFolderPath 函数 （shlobj_core.h）

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

Syntax

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

类型：HANDLE

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

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

为 hToken 参数分配一个值 -1 指示默认用户。 这样， SHSetKnownFolderPath 的客户端就可以为默认用户设置文件夹位置（如 桌面 文件夹）。 创建任何新用户帐户时，默认用户配置文件将重复，并包括 文档 和 桌面等特殊文件夹。 添加到默认用户文件夹的任何项目也会显示在任何新用户帐户中。 请注意，访问默认用户文件夹需要管理员权限。

[in] pszPath

类型：PCWSTR

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

返回值

类型：HRESULT

如果成功，则返回S_OK;否则返回错误值，包括以下内容：

注解

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

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

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

不能对类型 KF_CATEGORY_FIXED 和 KF_CATEGORY_VIRTUAL的文件夹调用此函数。

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

要求

另请参阅

IKnownFolder：：GetPath

IKnownFolder：：SetPath

IKnownFolderManager：：Redirect

已知文件夹示例

SHGetKnownFolderIDList

SHGetKnownFolderPath