SHGetFolderPathA 函数 (shlobj_core.h)

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

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

 

语法

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

参数

[in] hwnd

类型：HWND

保留。

[in] csidl

类型： int

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

[in] hToken

类型： 句柄

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

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

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

当 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 (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

类型： LPTSTR

指向 长度为 null 的字符串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, ...);
}

要求

要求	值
最低受支持的客户端	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