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。 此類型最常用的資料夾是 Documents。

當 hToken 為非NULL時，呼叫進程會負責正確的模擬。 呼叫進程必須具有特定用戶的適當安全性許可權，包括TOKEN_QUERY和TOKEN_IMPERSONATE，而且目前必須掛接使用者的登錄區。 如需訪問控制問題的進一步討論，請參閱 訪問控制。

將 hToken 參數指派為 -1 值，表示預設使用者。 這可讓 SHGetFolderPath 的用戶端尋找預設使用者的資料夾位置（例如 Desktop 資料夾）。 建立任何新的使用者帳戶時，預設使用者配置檔會重複，並包含特殊資料夾，例如[我的檔和桌面]。 任何新增至 [預設使用者] 資料夾的專案也會出現在任何新的使用者帳戶中。

[in] dwFlags

類型：DWORD

指定要傳回之路徑的旗標。 這個值用於與 KNOWNFOLDERID 相關聯的資料夾（或 CSIDL）可以由使用者或系統管理員移動、重新命名、重新導向或漫遊跨語言。

SHGetFolderPath 的已知資料夾系統可讓使用者或系統管理員將已知資料夾重新導向至符合其需求的位置。 呼叫 IKnownFolderManager：：Redirect，以設定與 SHGFP_TYPE_CURRENT 旗標相關聯之資料夾的 “current” 值來達成此目的。

如果使用者或系統管理員未將資料夾重新導向至別處，則會藉由指定SHGFP_TYPE_DEFAULT旗標來擷取資料夾的預設值。 這個值可用來實作已知資料夾的「還原預設值」功能。

例如，FOLDERID_Music （CSIDL_MYMUSIC） 的預設值 （SHGFP_TYPE_DEFAULT） 是 “C：\Users\使用者名稱\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 值，包括下列各項：

• 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