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

類型： HANDLE

可用來代表特定使用者的 存取令牌 。

Microsoft Windows 2000 和更早版本： 一律將此參數設定為 NULL。

Windows XP 和更新版本： 此參數通常會設定為 NULL，但您可能需要為具有多個使用者但視為屬於單一用戶的資料夾，將非 NULL 值指派給 hToken 。 此類型最常用的資料夾是 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

類型： 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 Professional、Windows XP [僅限桌面應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	shlobj_core.h (包含 Shlobj.h、Shlobj_core.h)
程式庫	Shell32.lib
Dll	Shell32.dll (5.0 版或更新版本)

另請參閱

IKnownFolder：：GetPath