Fungsi SHGetFileInfoA (shellapi.h)
Mengambil informasi tentang objek dalam sistem file, seperti file, folder, direktori, atau akar drive.
Sintaks
DWORD_PTR SHGetFileInfoA(
[in] LPCSTR pszPath,
DWORD dwFileAttributes,
[in, out] SHFILEINFOA *psfi,
UINT cbFileInfo,
UINT uFlags
);
Parameter
[in] pszPath
Jenis: LPCTSTR
Penunjuk ke string yang dihentikan null dengan panjang maksimum MAX_PATH yang berisi jalur dan nama file. Jalur absolut dan relatif valid.
Jika parameter uFlags menyertakan bendera SHGFI_PIDL , parameter ini harus menjadi alamat struktur ITEMIDLIST (PIDL) yang berisi daftar pengidentifikasi item yang secara unik mengidentifikasi file dalam namespace Shell. PIDL harus menjadi PIDL yang sepenuhnya memenuhi syarat. PIDL relatif tidak diperbolehkan.
Jika parameter uFlags menyertakan bendera SHGFI_USEFILEATTRIBUTES , parameter ini tidak harus menjadi nama file yang valid. Fungsi akan dilanjutkan seolah-olah file ada dengan nama yang ditentukan dan dengan atribut file yang diteruskan dalam parameter dwFileAttributes . Ini memungkinkan Anda untuk mendapatkan informasi tentang jenis file dengan hanya meneruskan ekstensi untuk pszPath dan meneruskan FILE_ATTRIBUTE_NORMAL di dwFileAttributes.
String ini dapat menggunakan nama file pendek (formulir 8.3) atau panjang.
dwFileAttributes
Jenis: DWORD
Kombinasi satu atau beberapa bendera atribut file (FILE_ATTRIBUTE_ nilai seperti yang didefinisikan dalam Winnt.h). Jika uFlags tidak menyertakan bendera SHGFI_USEFILEATTRIBUTES , parameter ini diabaikan.
[in, out] psfi
Jenis: SHFILEINFO*
Arahkan ke struktur SHFILEINFO untuk menerima informasi file.
cbFileInfo
Jenis: UINT
Ukuran, dalam byte, dari struktur SHFILEINFO yang ditujukkan oleh parameter psfi .
uFlags
Jenis: UINT
Bendera yang menentukan informasi file yang akan diambil. Parameter ini bisa menjadi kombinasi dari nilai berikut.
SHGFI_ADDOVERLAYS (0x000000020)
Versi 5.0. Terapkan overlay yang sesuai ke ikon file. Bendera SHGFI_ICON juga harus diatur.
SHGFI_ATTR_SPECIFIED (0x000020000)
Ubah SHGFI_ATTRIBUTES untuk menunjukkan bahwa dwAttributes anggota struktur SHFILEINFO di psfi berisi atribut tertentu yang diinginkan. Atribut ini diteruskan ke IShellFolder::GetAttributesOf. Jika bendera ini tidak ditentukan, 0xFFFFFFFF diteruskan ke IShellFolder::GetAttributesOf, meminta semua atribut. Bendera ini tidak dapat ditentukan dengan bendera SHGFI_ICON .
SHGFI_ATTRIBUTES (0x000000800)
Ambil atribut item. Atribut disalin ke anggota dwAttributes dari struktur yang ditentukan dalam parameter psfi . Ini adalah atribut yang sama yang diperoleh dari IShellFolder::GetAttributesOf.
SHGFI_DISPLAYNAME (0x000000200)
Ambil nama tampilan untuk file, yang merupakan nama seperti yang muncul di Windows Explorer. Nama disalin ke anggota szDisplayName dari struktur yang ditentukan dalam psfi. Nama tampilan yang dikembalikan menggunakan nama file panjang, jika ada, bukan bentuk 8,3 dari nama file. Perhatikan bahwa nama tampilan dapat dipengaruhi oleh pengaturan seperti apakah ekstensi ditampilkan.
SHGFI_EXETYPE (0x000002000)
Ambil jenis file yang dapat dieksekusi jika pszPath mengidentifikasi file yang dapat dieksekusi. Informasi dikemas ke dalam nilai yang dikembalikan. Bendera ini tidak dapat ditentukan dengan bendera lain.
SHGFI_ICON (0x000000100)
Ambil handel ke ikon yang mewakili file dan indeks ikon dalam daftar gambar sistem. Handel disalin ke anggota hIcon struktur yang ditentukan oleh psfi, dan indeks disalin ke anggota iIcon .
SHGFI_ICONLOCATION (0x000001000)
Ambil nama file yang berisi ikon yang mewakili file yang ditentukan oleh pszPath, seperti yang dikembalikan oleh metode IExtractIcon::GetIconLocation dari handler ikon file. Ambil juga indeks ikon dalam file tersebut. Nama file yang berisi ikon disalin ke anggota szDisplayName dari struktur yang ditentukan oleh psfi. Indeks ikon disalin ke anggota iIcon struktur tersebut.
SHGFI_LARGEICON (0x000000000)
Ubah SHGFI_ICON, menyebabkan fungsi mengambil ikon besar file. Bendera SHGFI_ICON juga harus diatur.
SHGFI_LINKOVERLAY (0x000008000)
Ubah SHGFI_ICON, menyebabkan fungsi menambahkan overlay tautan ke ikon file. Bendera SHGFI_ICON juga harus diatur.
SHGFI_OPENICON (0x000000002)
Ubah SHGFI_ICON, menyebabkan fungsi mengambil ikon buka file. Juga digunakan untuk memodifikasi SHGFI_SYSICONINDEX, menyebabkan fungsi mengembalikan handel ke daftar gambar sistem yang berisi ikon buka kecil file. Objek kontainer menampilkan ikon terbuka untuk menunjukkan bahwa kontainer terbuka. Bendera SHGFI_ICON dan/atau SHGFI_SYSICONINDEX juga harus diatur.
SHGFI_OVERLAYINDEX (0x000000040)
Versi 5.0. Mengembalikan indeks ikon overlay. Nilai indeks overlay dikembalikan dalam delapan bit atas anggota iIcon dari struktur yang ditentukan oleh psfi. Bendera ini mengharuskan SHGFI_ICON diatur juga.
SHGFI_PIDL (0x000000008)
Menunjukkan bahwa pszPath adalah alamat struktur ITEMIDLIST daripada nama jalur.
SHGFI_SELECTED (0x000010000)
Ubah SHGFI_ICON, menyebabkan fungsi memadukan ikon file dengan warna sorotan sistem. Bendera SHGFI_ICON juga harus diatur.
SHGFI_SHELLICONSIZE (0x000000004)
Ubah SHGFI_ICON, menyebabkan fungsi mengambil ikon berukuran Shell. Jika bendera ini tidak ditentukan, fungsi akan mengukur ikon sesuai dengan nilai metrik sistem. Bendera SHGFI_ICON juga harus diatur.
SHGFI_SMALLICON (0x000000001)
Ubah SHGFI_ICON, menyebabkan fungsi mengambil ikon kecil file. Juga digunakan untuk memodifikasi SHGFI_SYSICONINDEX, menyebabkan fungsi mengembalikan handel ke daftar gambar sistem yang berisi gambar ikon kecil. Bendera SHGFI_ICON dan/atau SHGFI_SYSICONINDEX juga harus diatur.
SHGFI_SYSICONINDEX (0x000004000)
Ambil indeks ikon daftar gambar sistem. Jika berhasil, indeks disalin ke anggota iIconpsfi. Nilai yang dikembalikan adalah handel ke daftar gambar sistem. Hanya gambar yang indeksnya berhasil disalin ke iIcon yang valid. Mencoba mengakses gambar lain dalam daftar gambar sistem akan mengakibatkan perilaku yang tidak ditentukan.
SHGFI_TYPENAME (0x000000400)
Ambil string yang menjelaskan jenis file. String disalin ke anggota szTypeName dari struktur yang ditentukan dalam psfi.
SHGFI_USEFILEATTRIBUTES (0x000000010)
Menunjukkan bahwa fungsi tidak boleh mencoba mengakses file yang ditentukan oleh pszPath. Sebaliknya, itu harus bertindak seolah-olah file yang ditentukan oleh pszPath ada dengan atribut file yang diteruskan dalam dwFileAttributes. Bendera ini tidak dapat digabungkan dengan bendera SHGFI_ATTRIBUTES, SHGFI_EXETYPE, atau SHGFI_PIDL .
Mengembalikan nilai
Jenis: DWORD_PTR
Mengembalikan nilai yang maknanya tergantung pada parameter uFlags .
Jika uFlags tidak berisi SHGFI_EXETYPE atau SHGFI_SYSICONINDEX, nilai yang dikembalikan bukan nol jika berhasil, atau nol sebaliknya.
Jika uFlags berisi bendera SHGFI_EXETYPE , nilai yang dikembalikan menentukan jenis file yang dapat dieksekusi. Ini akan menjadi salah satu nilai berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
File yang tidak dapat dieksekusi atau kondisi kesalahan. |
|
Aplikasi Windows. |
|
File .exe atau .com MS-DOS |
|
Aplikasi konsol atau file .bat |
Keterangan
Anda harus memanggil fungsi ini dari utas latar belakang. Kegagalan untuk melakukannya dapat menyebabkan UI berhenti merespons.
Jika SHGetFileInfo mengembalikan handel ikon di anggota hIcon struktur SHFILEINFO yang ditujukkan oleh psfi, Anda bertanggung jawab untuk membebaskannya dengan DestroyIcon ketika Anda tidak lagi membutuhkannya.
Saat Anda menggunakan bendera SHGFI_EXETYPE dengan aplikasi Windows, versi Windows dari executable diberikan dalam HIWORD dari nilai yang dikembalikan. Versi ini dikembalikan sebagai nilai heksadesimal. Untuk detail tentang persamaan nilai ini dengan versi Windows tertentu, lihat Menggunakan Header Windows.
Contoh
Contoh kode berikut menggunakan SHGetFileInfo untuk mengambil nama tampilan Keranjang Sampah, yang diidentifikasi oleh PIDL-nya.
LPITEMIDLIST pidl = NULL;
hr = SHGetFolderLocation(NULL, CSIDL_BITBUCKET, NULL, 0, &pidl);
if (SUCCEEDED(hr))
{
SHFILEINFOW sfi = {0};
hr = SHGetFileInfo((LPCTSTR)pidl,
-1,
&sfi,
sizeof(sfi),
SHGFI_PIDL | SHGFI_DISPLAYNAME)
if (SUCCEEDED(hr))
{
// The display name is now held in sfi.szDisplayName.
}
}
ILFree(pidl);
Catatan
Header shellapi.h mendefinisikan SHGetFileInfo sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor 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 XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | shellapi.h |
| Pustaka | Shell32.lib |
| DLL | Shell32.dll (versi 4.0 atau yang lebih baru) |