Fungsi SHGetFolderLocation (shlobj_core.h)

Artikel
03/15/2023

Dihentikan. Mengambil jalur folder sebagai struktur ITEMIDLIST .

Sintaks

SHSTDAPI SHGetFolderLocation(
  [in]  HWND             hwnd,
  [in]  int              csidl,
  [in]  HANDLE           hToken,
  [in]  DWORD            dwFlags,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Parameter

[in] hwnd

Jenis: HWND

Dicadangkan.

[in] csidl

Jenis: int

Nilai CSIDL yang mengidentifikasi folder yang akan ditemukan. Folder yang terkait dengan CSIDL mungkin tidak ada pada sistem tertentu.

[in] hToken

Jenis: HANDEL

Token akses yang dapat digunakan untuk mewakili pengguna tertentu. Biasanya diatur ke NULL, tetapi mungkin diperlukan ketika ada beberapa pengguna untuk folder yang diperlakukan sebagai milik satu pengguna. Folder yang paling umum digunakan dari jenis ini adalah Dokumen Saya. Aplikasi panggilan bertanggung jawab atas peniruan yang benar ketika hToken bukan NULL. Ini harus memiliki hak keamanan yang sesuai untuk pengguna tertentu, 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 SHGetFolderLocation 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 Saya dan Desktop. Item apa pun yang ditambahkan ke folder Pengguna Default juga muncul di akun pengguna baru mana pun.

[in] dwFlags

Jenis: DWORD

[out] ppidl

Jenis: PIDLIST_ABSOLUTE*

Alamat penunjuk ke struktur daftar pengidentifikasi item yang menentukan lokasi folder relatif terhadap akar namespace layanan (desktop). Parameter ppidl diatur ke NULL jika gagal. Aplikasi panggilan bertanggung jawab untuk membebaskan sumber daya ini dengan memanggil ILFree.

Mengembalikan nilai

Jenis: HRESULT

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

Menampilkan kode	Deskripsi
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	CSIDL di nFolder valid tetapi folder tidak ada.
E_INVALIDARG	CSIDL di nFolder tidak valid.

Keterangan

Catatan Pada Windows Vista, fungsi ini hanyalah pembungkus untuk SHGetKnownFolderIDList. Nilai CSIDL diterjemahkan ke KNOWNFOLDERID dan SHGetKnownFolderIDList terkait dipanggil. Aplikasi baru harus menggunakan sistem folder yang diketahui daripada sistem CSIDL yang lebih lama, yang hanya didukung untuk kompatibilitas mundur.

Fungsi SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation, dan SHGetSpecialFolderPath adalah cara yang disukai untuk mendapatkan handel ke folder pada sistem yang lebih lama daripada Windows Vista. Fungsi seperti ExpandEnvironmentStrings yang menggunakan nama variabel lingkungan secara langsung, dalam bentuk %VariableName%, mungkin tidak dapat diandalkan.

Fungsi ini adalah superset dari SHGetSpecialFolderLocation, disertakan dengan versi Shell yang lebih lama.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional, 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)
Pustaka	Shell32.lib
DLL	Shell32.dll (versi 5.0 atau yang lebih baru)

Lihat juga

IKnownFolder::GetIDList