SHGetFolderPathW 函数 （shlobj_core.h）

荒废的。 获取由 CSIDL 值标识的文件夹的路径。

Note 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

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

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

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

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

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

[in] dwFlags

类型：DWORD

指定要返回的路径的标志。 如果与 KNOWNFOLDERID（或 CSIDL）关联的文件夹可以由用户或管理员移动、重命名、重定向或漫游，则使用此值。

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

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

例如，FOLDERID_Music（SHGFP_TYPE_DEFAULTCSIDL_MYMUSIC）的默认值为“C：\Users\用户名\Music”。 如果重定向了文件夹，则当前值（SHGFP_TYPE_CURRENT）可能是“D：\Music”。 如果文件夹尚未重定向，则SHGFP_TYPE_DEFAULT并SHGFP_TYPE_CURRENT检索相同的路径。

SHGFP_TYPE_CURRENT

检索文件夹的当前路径。

SHGFP_TYPE_DEFAULT

检索文件夹的默认路径。

[out] pszPath

类型：LPWSTR

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

返回值

类型：HRESULT

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

言论

此函数是 SHGetSpecialFolderPath的超集。

仅支持某些 CSIDL 值，包括：

• CSIDL_ADMINTOOLS
• CSIDL_APPDATA
• CSIDL_COMMON_ADMINTOOLS
• CSIDL_COMMON_APPDATA
• CSIDL_COMMON_DOCUMENTS
• CSIDL_COOKIES
• CSIDL_FLAG_CREATE
• CSIDL_FLAG_DONT_VERIFY
• CSIDL_HISTORY
• CSIDL_INTERNET_CACHE
• CSIDL_LOCAL_APPDATA
• CSIDL_MYPICTURES
• CSIDL_PERSONAL
• CSIDL_PROGRAM_FILES
• CSIDL_PROGRAM_FILES_COMMON
• CSIDL_SYSTEM
• CSIDL_WINDOWS

例子

下面的代码示例使用 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 Professional、Windows XP [仅限桌面应用]
支持的最低服务器	Windows 2000 Server [仅限桌面应用]
目标平台	窗户
标头	shlobj_core.h（包括 Shlobj.h、Shlobj_core.h）
库	Shell32.lib
DLL	Shell32.dll （版本 5.0 或更高版本）

另请参阅

IKnownFolder：：GetPath