SHGetFolderPathW 函数 (shlobj_core.h)

  • 项目

已弃用。 获取由 CSIDL 值标识的文件夹的路径。

注意 从 Windows Vista 起，此函数只是 SHGetKnownFolderPath 的包装器。 CSIDL 值将转换为其关联的 KNOWNFOLDERID ，然后调用 SHGetKnownFolderPath 。 新应用程序应使用已知的文件夹系统，而不是较旧的 CSIDL 系统，后者仅支持向后兼容性。
 

语法

SHFOLDERAPI SHGetFolderPathW(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPWSTR pszPath
);

参数

[in] hwnd

类型：HWND

保留。

[in] csidl

类型： int

标识要检索其路径的文件夹的 CSIDL 值。 只有真实文件夹有效。 如果指定了虚拟文件夹，此函数将失败。 可以通过将文件夹的 CSIDL 与 CSIDL_FLAG_CREATE组合来强制创建文件夹。

[in] hToken

类型： HANDLE

可用于表示特定用户的 访问令牌 。

Microsoft Windows 2000 及更早版本： 始终将此参数设置为 NULL。

Windows XP 及更高版本：此参数通常设置为 NULL，但对于可以包含多个用户但被视为属于单个用户的文件夹，可能需要为 hToken 分配非 NULL 值。 此类型最常用的文件夹是 Documents。

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

为 hToken 参数分配值 -1 表示默认用户。 这使 SHGetFolderPath 的客户端能够查找文件夹位置 (，例如默认用户的 Desktop 文件夹) 。 创建任何新用户帐户时，默认用户配置文件将重复，其中包含特殊文件夹，例如“我的文档”和“桌面”。 添加到“默认用户”文件夹的任何项目也会显示在任何新的用户帐户中。

[in] dwFlags

类型：DWORD

指定要返回的路径的标志。 当用户或管理员可以跨语言移动、重命名、重定向或漫游 与 KNOWNFOLDERID (或 CSIDL) 关联的文件夹时，可以使用此值。

SHGetFolderPath 的已知文件夹系统允许用户或管理员将已知文件夹重定向到满足其需求的位置。 这是通过调用 IKnownFolderManager：：Redirect 实现的，后者设置与SHGFP_TYPE_CURRENT标志关联的文件夹的“当前”值。

文件夹的默认值（如果用户或管理员未将文件夹重定向到其他位置），则通过指定 SHGFP_TYPE_DEFAULT 标志来检索该文件夹的位置。 此值可用于实现已知文件夹的“还原默认值”功能。

例如， FOLDERID_Music (CSIDL_MYMUSIC) 的 默认值 (SHGFP_TYPE_DEFAULT) 为 “C：\Users\user name\Music”。 如果重定向了文件夹，则 (SHGFP_TYPE_CURRENT) 的当前值可能是“D：\Music”。 如果尚未重定向文件夹，则SHGFP_TYPE_DEFAULT和SHGFP_TYPE_CURRENT检索相同的路径。

SHGFP_TYPE_CURRENT

检索文件夹的当前路径。

SHGFP_TYPE_DEFAULT

检索文件夹的默认路径。

[out] pszPath

类型： LPWSTR

指向长度为 null 的字符串MAX_PATH的指针，该字符串将接收路径。 如果发生错误或返回S_FALSE，则此字符串将为空。 返回的路径不包括尾随反斜杠。 例如，返回“C：\Users”而不是“C：\Users\”。

返回值

类型： HRESULT

如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。

注解

此函数是 SHGetSpecialFolderPath 的超集。

仅支持某些 CSIDL 值，包括：

示例

下面的代码示例使用 SHGetFolderPath 查找或创建文件夹，然后在其中创建文件。

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

注意

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

要求

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

另请参阅

IKnownFolder：：GetPath