Fungsi SHSetKnownFolderPath (shlobj_core.h)

Artikel
08/26/2023

Mengalihkan folder yang diketahui ke lokasi baru.

Sintaks

HRESULT SHSetKnownFolderPath(
  [in] REFKNOWNFOLDERID rfid,
  [in] DWORD            dwFlags,
  [in] HANDLE           hToken,
  [in] PCWSTR           pszPath
);

Parameter

[in] rfid

Jenis: REFKNOWNFOLDERID

GUID yang mengidentifikasi folder yang diketahui.

[in] dwFlags

Jenis: DWORD

Baik 0 atau nilai berikut.

KF_FLAG_DONT_UNEXPAND

Jika bendera ini diatur, bagian jalur yang direferensikan oleh pszPath dapat diwakili oleh string lingkungan seperti %USERPROFILE%.

[in] hToken

Jenis: HANDEL

Token akses yang 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.

Menetapkan parameter hToken nilai -1 menunjukkan Pengguna Default. Ini memungkinkan klien SHSetKnownFolderPath untuk mengatur lokasi folder (seperti folder Desktop ) untuk Pengguna Default. Profil pengguna Pengguna Default diduplikasi saat akun pengguna baru dibuat, dan menyertakan folder khusus seperti Dokumen dan Desktop. Item apa pun yang ditambahkan ke folder Pengguna Default juga muncul di akun pengguna baru mana pun. Perhatikan bahwa akses ke folder Pengguna Default memerlukan hak istimewa administrator.

[in] pszPath

Jenis: PCWSTR

Penunjuk ke jalur baru folder. Ini adalah string Unicode panjang yang dihentikan null MAX_PATH. Jalur ini tidak boleh memiliki panjang nol.

Mengembalikan nilai

Jenis: HRESULT

Mengembalikan S_OK jika berhasil, atau nilai kesalahan jika tidak, termasuk yang berikut ini:

Menampilkan kode	Deskripsi
E_INVALIDARG	Antara lain, nilai ini dapat menunjukkan bahwa parameter rfid mereferensikan KNOWNFOLDERID yang tidak ada pada sistem. Tidak semua nilai KNOWNFOLDERID ada di semua sistem. Gunakan IKnownFolderManager::GetFolderIds untuk mengambil kumpulan nilai KNOWNFOLDERID untuk sistem saat ini.

Keterangan

Fungsi ini menggantikan SHSetFolderPath. Fungsi lama itu sekarang hanyalah pembungkus untuk SHSetKnownFolderPath.

Pemanggil fungsi ini harus memiliki hak istimewa Administrator. Untuk memanggil fungsi ini pada folder umum yang diketahui, pemanggil harus memiliki hak istimewa Administrator. Untuk folder per pengguna yang diketahui, pemanggil hanya memerlukan hak istimewa Pengguna.

Beberapa folder yang diketahui, misalnya, folder Dokumen , adalah per pengguna. Setiap pengguna memiliki jalur yang berbeda untuk folder Dokumen mereka. Jika hTokenadalah NULL, API mencoba mengakses instans folder aplikasi panggilan, yang merupakan pengguna saat ini. Jika hToken adalah token pengguna yang valid, API mencoba meniru pengguna menggunakan token ini dan mencoba mengakses instans pengguna tersebut.

Fungsi ini tidak dapat dipanggil pada folder bertipe KF_CATEGORY_FIXED dan KF_CATEGORY_VIRTUAL.

Untuk memanggil fungsi ini pada folder jenis KF_CATEGORY_COMMON, aplikasi panggilan harus berjalan dengan hak istimewa yang ditingkatkan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	shlobj_core.h (termasuk Shlobj.h)
DLL	Shell32.dll (versi 6.0.6000 atau yang lebih baru)