共用方式為

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 所指向的字串 值為空字串 （“”） 長度為零。

言論

Note Windows Vista，此函式只是 SHSetKnownFolderPath的包裝函式。 CSIDL 值會轉譯成其相關聯的 KNOWNFOLDERID，並呼叫 SHSetKnownFolderPath 。 新的應用程式應該使用已知的資料夾系統，而不是舊版 CSIDL 系統，這隻支援回溯相容性。
 
SHSetFolderPath 不會依名稱從 Shell32.dll匯出。 若要使用 函式，您必須針對 SHSetFolderPathA 呼叫 GetProcAddress，或針對 SHSetFolderPathW 或序數 232 來取得函式指標。

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

注意

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

要求

要求 價值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 shlobj_core.h （包括 Shlobj.h， Shlobj_core.h）
連結庫 Shell32.lib
DLL Shell32.dll 版 （5.0 版或更新版本）

另請參閱

IKnownFolder：：SetPath