通过

SHSetFolderPathA 函数 （shlobj_core.h）

  • 项目

荒废的。 为其 CSIDL 标识的系统文件夹分配新路径。

语法

HRESULT SHSetFolderPathA(
  [in] int    csidl,
  [in] HANDLE hToken,
  [in] DWORD  dwFlags,
  [in] LPCSTR pszPath
);

参数

[in] csidl

类型：int

CSIDL 值，该值标识要设置其路径的文件夹。 只有物理文件夹有效。 如果指定了虚拟文件夹，此函数将失败。

将 CSIDL_FLAG_DONT_UNEXPAND 值添加到 CSIDL，以确保字符串与提供的注册表完全一样写入注册表。 如果未包含 CSIDL_FLAG_DONT_UNEXPAND 标志，则路径的某些部分可能会被环境字符串（如 %USERPROFILE%）替换。

[in] hToken

类型：HANDLE

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

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

[in] dwFlags

类型：DWORD

保留。 必须设置为 0。

[in] pszPath

类型：LPCTSTR

指向长度为 null 的字符串的指针，该字符串包含文件夹的新路径MAX_PATH。 此值不能 NULL，字符串长度不能为零。

返回值

类型：HRESULT

返回标准 HRESULT 代码，包括：

返回代码 描述
S_OK
 已成功更新文件夹的路径。
E_INVALIDARG
 多个错误条件导致返回此值，包括以下内容：
  • csidl 值无效。
  • csidl 值不引用虚拟文件夹。
  • csidl 值不引用系统文件夹。
  • csidl 值是指无法重命名或移动的文件夹。
  • dwFlags 值不是 0（零）。
  • pszPath 值 NULL。
  • pszPath 值指向的字符串是长度为零的空字符串（“”）。

言论

Note Windows Vista，此函数只是 SHSetKnownFolderPath的包装器。 CSIDL 值将转换为其关联的 KNOWNFOLDERID，并调用 SHSetKnownFolderPath。 新应用程序应使用已知的文件夹系统，而不是旧的 CSIDL 系统，后者仅支持向后兼容性。
 
SHSetFolderPath 未按名称从 Shell32.dll导出。 若要使用该函数，必须对 SHSetFolderPathA（对于 ANSI 字符串）或序号 232 调用 GetProcAddress 来获取函数指针。若要获取函数指针，则必须为 SHSetFolderPathW 调用序号 231。

建议将路径表示为 Unicode 字符串，因为文件夹名称可能包含 ANSI 中无法表达的 Unicode 字符。

注意

shlobj_core.h 标头将 SHSetFolderPath 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows XP [仅限桌面应用]
支持的最低服务器 Windows Server 2003 [仅限桌面应用]
目标平台 窗户
标头 shlobj_core.h（包括 Shlobj.h、Shlobj_core.h）
库 Shell32.lib
DLL Shell32.dll （版本 5.0 或更高版本）

另请参阅

IKnownFolder：：SetPath