Fungsi SHGetKnownFolderIDList (shlobj_core.h)

Artikel
03/15/2023

Mengambil jalur folder yang dikenal sebagai struktur ITEMIDLIST .

Sintaks

HRESULT SHGetKnownFolderIDList(
  [in]  REFKNOWNFOLDERID rfid,
  [in]  DWORD            dwFlags,
  [in]  HANDLE           hToken,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Parameter

[in] rfid

Jenis: REFKNOWNFOLDERID

Referensi ke KNOWNFOLDERID yang mengidentifikasi folder. Folder yang terkait dengan ID folder yang diketahui mungkin tidak ada pada sistem tertentu.

[in] dwFlags

Jenis: DWORD

Bendera yang menentukan opsi pengambilan khusus. Nilai ini bisa 0; jika tidak, itu adalah 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 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 SHGetKnownFolderIDList untuk menemukan 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.

[out] ppidl

Jenis: PIDLIST_ABSOLUTE*

Ketika metode ini kembali, berisi penunjuk ke PIDL folder. Parameter ini diteruskan tanpa diinisialisasi. Pemanggil bertanggung jawab untuk membebaskan PIDL yang dikembalikan ketika tidak lagi diperlukan dengan memanggil ILFree.

Nilai kembali

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

Fungsi ini menggantikan SHGetFolderLocation. Fungsi lama itu sekarang hanyalah pembungkus untuk SHGetKnownFolderIDList.

Pemanggil yang menggunakan fungsi ini harus memiliki setidaknya hak istimewa Pengguna.

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

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)
Pustaka	Shell32.lib
DLL	Shell32.dll (versi 6.0.6000 atau yang lebih baru)

Lihat juga

IKnownFolder::GetPath

Sampel Folder yang Diketahui

SHGetKnownFolderPath

SHSetKnownFolderPath

Bagikan melalui