Fungsi SHSetFolderPathA (shlobj_core.h)

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

Sintaksis

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: HANDLE

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 untuk 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 Kontrol Akses untuk diskusi lebih lanjut tentang masalah kontrol akses.

[in] dwFlags

Jenis: DWORD

Dipesan. 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 dapat null, dan string tidak boleh memiliki panjang nol.

Mengembalikan nilai

Jenis: HRESULT

Mengembalikan kode HRESULT standar, termasuk yang berikut ini:

Mengembalikan 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 NULL. String yang ditujukkan oleh nilai pszPath adalah string kosong ("") dari panjang nol.

Komentar

Note Pada Windows Vista, fungsi ini hanyalah pembungkus untuk SHSetKnownFolderPath. Nilai CSIDL diterjemahkan ke KNOWNFOLDERID terkait dan SHSetKnownFolderPath 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.

Nota

Header shlobj_core.h mendefinisikan SHSetFolderPath sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosektor 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

Syarat	Nilai
klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Platform Target	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