Bagikan melalui

Fungsi SHSetFolderPathA (shlobj_core.h)

  • Artikel

Dihentikan. Menetapkan jalur baru ke folder sistem yang diidentifikasi oleh CSIDL-nya.

Sintaks

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

Parameter

[in] csidl

Jenis: int

Nilai CSIDL yang mengidentifikasi folder yang jalurnya akan diatur. Hanya folder fisik yang valid. Jika folder virtual ditentukan, fungsi ini gagal.

Tambahkan nilai CSIDL_FLAG_DONT_UNEXPAND ke CSIDL untuk memastikan bahwa string ditulis ke registri persis seperti yang disediakan. Jika bendera CSIDL_FLAG_DONT_UNEXPAND tidak disertakan, bagian jalur dapat digantikan oleh string lingkungan, seperti %USERPROFILE%.

[in] hToken

Jenis: HANDEL

Token akses yang dapat digunakan untuk mewakili pengguna tertentu. Parameter ini biasanya diatur ke NULL, dalam hal ini fungsi mencoba mengakses instans folder pengguna saat ini. Namun, Anda mungkin perlu menetapkan nilai ke hToken untuk folder yang dapat memiliki beberapa pengguna tetapi diperlakukan sebagai milik satu pengguna. Folder yang paling umum digunakan dari jenis ini adalah Dokumen.

Aplikasi panggilan bertanggung jawab atas peniruan yang benar ketika hToken non-null. Ini harus memiliki hak istimewa keamanan yang sesuai untuk pengguna tertentu, termasuk TOKEN_QUERY dan TOKEN_IMPERSONATE, dan sarang registri pengguna saat ini harus dipasang. Lihat Access Control untuk diskusi lebih lanjut tentang masalah kontrol akses.

[in] dwFlags

Jenis: DWORD

Dicadangkan. Harus diatur ke 0.

[in] pszPath

Jenis: LPCTSTR

Penunjuk ke string panjang yang dihentikan null MAX_PATH yang berisi jalur baru folder. Nilai ini tidak boleh NULL, dan string tidak boleh memiliki panjang nol.

Nilai kembali

Jenis: HRESULT

Mengembalikan kode HRESULT standar, termasuk yang berikut ini:

Menampilkan kode Deskripsi
S_OK
 Jalur folder berhasil diperbarui.
E_INVALIDARG
 Beberapa kondisi kesalahan menyebabkan pengembalian nilai ini, termasuk yang berikut ini:
  • Nilai csidl tidak valid.
  • Nilai csidl tidak merujuk ke folder virtual.
  • Nilai csidl tidak merujuk ke folder sistem.
  • Nilai csidl mengacu pada folder yang tidak dapat diganti namanya atau dipindahkan.
  • Nilai dwFlags bukan 0 (nol).
  • Nilai pszPath adalah NULL.
  • String yang ditujukkan oleh nilai pszPath adalah string kosong ("") dengan panjang nol.

Keterangan

Catatan Pada Windows Vista, fungsi ini hanyalah pembungkus untuk SHSetKnownFolderPath. Nilai CSIDL diterjemahkan ke KNOWNFOLDERID dan SHSetKnownFolderPath terkait dipanggil. Aplikasi baru harus menggunakan sistem folder yang diketahui daripada sistem CSIDL yang lebih lama, yang hanya didukung untuk kompatibilitas mundur.
 
SHSetFolderPath tidak diekspor berdasarkan nama dari Shell32.dll. Untuk menggunakan fungsi ini, Anda harus memanggil GetProcAddress dengan ordinal 231 untuk SHSetFolderPathA (untuk string ANSI) atau ordinal 232 untuk SHSetFolderPathW (untuk string Unicode) untuk mendapatkan penunjuk fungsi.

Disarankan agar jalur dinyatakan sebagai string Unicode karena nama folder mungkin berisi karakter Unicode yang tidak dapat diekspresikan di ANSI.

Catatan

Header shlobj_core.h mendefinisikan SHSetFolderPath sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows XP [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2003 [hanya aplikasi desktop]
Target Platform Windows
Header shlobj_core.h (termasuk Shlobj.h, Shlobj_core.h)
Pustaka Shell32.lib
DLL Shell32.dll (versi 5.0 atau yang lebih baru)

Lihat juga

IKnownFolder::SetPath