Fungsi SHGetKnownFolderItem (shlobj_core.h)

Artikel
03/02/2024

Mengambil objek IShellItem yang mewakili folder yang diketahui.

Sintaks

HRESULT SHGetKnownFolderItem(
  [in]  REFKNOWNFOLDERID  rfid,
  [in]  KNOWN_FOLDER_FLAG flags,
  [in]  HANDLE            hToken,
  [in]  REFIID            riid,
  [out] void              **ppv
);

Parameter

[in] rfid

Jenis: REFKNOWNFOLDERID

Referensi ke KNOWNFOLDERID, GUID yang mengidentifikasi folder yang berisi item.

[in] flags

Jenis: KNOWN_FOLDER_FLAG

Bendera yang menentukan opsi khusus yang digunakan dalam pengambilan folder yang diketahui IShellItem. Nilai ini dapat KF_FLAG_DEFAULT; jika tidak, satu atau beberapa nilai KNOWN_FOLDER_FLAG .

[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 hTokennon-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] riid

Jenis: REFIID

Referensi ke IID antarmuka yang mewakili item, biasanya IID_IShellItem atau IID_IShellItem2.

[out] ppv

Jenis: void**

Ketika metode ini kembali, berisi pointer antarmuka yang diminta dalam riid.

Mengembalikan nilai

Jenis: HRESULT

Mengembalikan S_OK jika berhasil, atau nilai kesalahan sebaliknya, 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

Pemanggil fungsi ini harus memiliki hak istimewa Administrator. Untuk memanggil fungsi ini pada folder publik 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 hToken adalah 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 7 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 R2 [hanya aplikasi desktop]
Target Platform	Windows
Header	shlobj_core.h (termasuk Shlobj.h)
Pustaka	Shell32.lib
DLL	Shell32.dll (versi 6.1 atau yang lebih baru)
Set API	ext-ms-win-shell-shell32-l1-2-1 (diperkenalkan dalam Windows 10, versi 10.0.10240)