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，但您可能需要針對可以有多個使用者但視為屬於單一使用者的資料夾，將非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\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 值，包括下列各項：

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

另請參閱

IKnownFolder：：GetPath