Fungsi SHGetFolderPathW (shlobj_core.h)

Artikel
03/04/2024

Dihentikan. Mendapatkan jalur folder yang diidentifikasi oleh nilai CSIDL .

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

Sintaks

SHFOLDERAPI SHGetFolderPathW(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPWSTR pszPath
);

Parameter

[in] hwnd

Jenis: HWND

Dicadangkan.

[in] csidl

Jenis: int

Nilai CSIDL yang mengidentifikasi folder yang jalurnya akan diambil. Hanya folder nyata yang valid. Jika folder virtual ditentukan, fungsi ini gagal. Anda dapat memaksa pembuatan folder dengan menggabungkan CSIDL folder dengan CSIDL_FLAG_CREATE.

[in] hToken

Jenis: HANDEL

Token akses yang dapat digunakan untuk mewakili pengguna tertentu.

Microsoft Windows 2000 dan yang lebih lama: Selalu atur parameter ini ke NULL.

Windows XP dan yang lebih baru: Parameter ini biasanya diatur ke NULL, tetapi Anda mungkin perlu menetapkan nilai non-NULL 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.

Proses panggilan bertanggung jawab atas peniruan yang benar ketika hToken bukan NULL. Proses panggilan harus memiliki hak 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 SHGetFolderPath 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

Bendera yang menentukan jalur yang akan dikembalikan. Nilai ini digunakan dalam kasus di mana folder yang terkait dengan KNOWNFOLDERID (atau CSIDL) dapat dipindahkan, diganti namanya, dialihkan, atau dijelajahi di seluruh bahasa oleh pengguna atau administrator.

Sistem folder yang diketahui yang mendasar SHGetFolderPath memungkinkan pengguna atau administrator untuk mengalihkan folder yang diketahui ke lokasi yang sesuai dengan kebutuhan mereka. Ini dicapai dengan memanggil IKnownFolderManager::Redirect, yang menetapkan nilai "saat ini" dari folder yang terkait dengan bendera SHGFP_TYPE_CURRENT.

Nilai default folder, yang merupakan lokasi folder jika pengguna atau administrator belum mengalihkannya ke tempat lain, diambil dengan menentukan bendera SHGFP_TYPE_DEFAULT. Nilai ini dapat digunakan untuk mengimplementasikan fitur "pulihkan default" untuk folder yang diketahui.

Misalnya, nilai default (SHGFP_TYPE_DEFAULT) untuk FOLDERID_Music (CSIDL_MYMUSIC) adalah "C:\Users\user name\Music". Jika folder dialihkan, nilai saat ini (SHGFP_TYPE_CURRENT) mungkin "D:\Music". Jika folder belum dialihkan, maka SHGFP_TYPE_DEFAULT dan SHGFP_TYPE_CURRENT mengambil jalur yang sama.

SHGFP_TYPE_CURRENT

Ambil jalur folder saat ini.

SHGFP_TYPE_DEFAULT

Ambil jalur default folder.

[out] pszPath

Jenis: LPWSTR

Penunjuk ke string panjang yang dihentikan null MAX_PATH yang akan menerima jalur. Jika terjadi kesalahan atau S_FALSE dikembalikan, string ini akan kosong. Jalur yang dikembalikan tidak menyertakan garis miring terbelakang. Misalnya, "C:\Users" dikembalikan daripada "C:\Users\".

Mengembalikan nilai

Jenis: HRESULT

Jika fungsi ini berhasil, fungsi akan mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT akan dikembalikan.

Keterangan

Fungsi ini adalah superset dari SHGetSpecialFolderPath.

Hanya beberapa nilai CSIDL yang didukung, termasuk yang berikut ini:

Contoh

Contoh kode berikut menggunakan SHGetFolderPath untuk menemukan atau membuat folder lalu membuat file di dalamnya.

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

Catatan

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

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional, Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	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::GetPath

Bagikan melalui