SHSetFolderPathA 函式 (shlobj_core.h)

已取代。 將新路徑指派給其 CSIDL 所識別的系統資料夾。

語法

HRESULT SHSetFolderPathA(
  [in] int    csidl,
  [in] HANDLE hToken,
  [in] DWORD  dwFlags,
  [in] LPCSTR pszPath
);

參數

[in] csidl

類型： int

CSIDL 值，識別要設定其路徑的資料夾。 只有實體資料夾有效。 如果指定了虛擬資料夾，此函式會失敗。

將 CSIDL_FLAG_DONT_UNEXPAND 值新增至 CSIDL，以確保字串會與提供的完全一樣寫入登錄。 如果未包含 CSIDL_FLAG_DONT_UNEXPAND 旗標，路徑的部分可能會由環境字串取代，例如 %USERPROFILE%。

[in] hToken

類型： HANDLE

可用來代表特定使用者的 存取令牌 。 此參數通常設定為 NULL，在此情況下，函式會嘗試存取目前使用者的資料夾實例。 不過，您可能需要為可有多個使用者但被視為屬於單一用戶的資料夾，將值指派給 hToken 。 此類型最常使用的資料夾是 Documents。

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

[in] dwFlags

類型： DWORD

保留的。 必須設定為 0。

[in] pszPath

類型： LPCTSTR

長度為 null 之字串的指標，MAX_PATH包含資料夾的新路徑。 這個值不能是 NULL，而且字串不能是零長度。

傳回值

類型： HRESULT

傳回標準 HRESULT 代碼，包括下列專案：

傳回碼	描述
S_OK	資料夾的路徑已成功更新。
E_INVALIDARG	數個錯誤狀況會造成此值的傳回，包括下列各項： csidl 值無效。 csidl 值不會參考虛擬資料夾。 csidl 值不會參考系統資料夾。 csidl 值是指無法重新命名或行動的資料夾。 dwFlags 值不是 0 (零) 。 pszPath 值為 NULL。 pszPath 值所指向的字串是空字串 (“”) 長度為零。

備註

注意 從 Windows Vista 開始，此函式只是 SHSetKnownFolderPath 的包裝函式。 CSIDL 值會轉譯為其相關聯的 KNOWNFOLDERID ，並呼叫 SHSetKnownFolderPath 。 新的應用程式應該使用已知的資料夾系統，而不是舊版 CSIDL 系統，這僅支援回溯相容性。

 

SHSetFolderPath 不是依名稱從 Shell32.dll 匯出。 若要使用 函式，您必須針對 ANSI) 字串呼叫具有序數 231 的 GetProcAddress (，) 或 SHSetFolderPathW 的序數 232 (，以取得函式指標。

建議將路徑表示為 Unicode 字串，因為資料夾名稱可能包含 ANSI 中無法表達的 Unicode 字元。

注意

shlobj_core.h 標頭會將SHSetFolderPath定義為別名，根據UNICODE預處理器常數的定義，自動選取此函式的ANSI或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	shlobj_core.h (包含 Shlobj.h、Shlobj_core.h)
程式庫	Shell32.lib
Dll	Shell32.dll (5.0 版或更新版本)

另請參閱

IKnownFolder：：SetPath