Fungsi SHGetFileInfoA (shellapi.h)

Mengambil informasi tentang objek dalam sistem file, seperti file, folder, direktori, atau akar drive.

Sintaksis

DWORD_PTR SHGetFileInfoA(
  [in]      LPCSTR      pszPath,
            DWORD       dwFileAttributes,
  [in, out] SHFILEINFOA *psfi,
            UINT        cbFileInfo,
            UINT        uFlags
);

Parameter

[in] pszPath

Jenis: LPCTSTR

Penunjuk ke stringnull 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 merupakan 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 (nilai FILE_ATTRIBUTE_ 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

Ukurannya, dalam byte, dari struktur SHFILEINFO yang ditunjukkan 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 pada 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 dwAttributes anggota 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 szDisplayName anggota struktur yang ditentukan dalam psfi. Nama tampilan yang dikembalikan menggunakan nama file panjang, jika ada, bukan formulir 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 pengembalian. 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 hIcon anggota 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 szDisplayName anggota 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 iIcon anggota struktur yang ditentukan oleh psfi. Bendera ini mengharuskan SHGFI_ICON diatur juga.

SHGFI_PIDL (0x000000008)

Tunjukkan 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 iIcon anggota psfi. 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 szTypeName anggota struktur yang ditentukan dalam psfi.

SHGFI_USEFILEATTRIBUTES (0x000000010)

Menunjukkan bahwa fungsi tidak boleh mencoba mengakses file yang ditentukan oleh pszPath. Sebaliknya, file 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 pengembalian menentukan jenis file yang dapat dieksekusi. Ini akan menjadi salah satu nilai berikut.

Mengembalikan kode	Deskripsi
0	File yang tidak dapat dieksekusi atau kondisi kesalahan.
LOWORD = NE atau PE dan HIWORD = versi Windows	Aplikasi Windows.
LOWORD = MZ dan HIWORD = 0	file MS-DOS .exe atau .com
LOWORD = PE dan HIWORD = 0	Aplikasi konsol atau file .bat

Komentar

Anda harus memanggil fungsi ini dari utas latar belakang. Kegagalan untuk melakukannya dapat menyebabkan UI berhenti merespons.

Jika SHGetFileInfo mengembalikan handel ikon di hIcon anggota struktur SHFILEINFO yang ditunjukkan oleh psfi, Anda bertanggung jawab untuk membebaskannya dengan DestroyIcon ketika Anda tidak lagi membutuhkannya.

Note Setelah Anda memiliki handel ke daftar gambar sistem, Anda dapat menggunakan Image List API untuk memanipulasinya seperti daftar gambar lainnya. Karena daftar gambar sistem dibuat berdasarkan per proses, Anda harus memperlakukannya sebagai objek baca-saja. Menulis ke daftar gambar sistem dapat menimpa atau menghapus salah satu gambar sistem, membuatnya tidak tersedia atau salah untuk sisa proses.

Anda harus menginisialisasi Model Objek Komponen (COM) dengan CoInitialize atau OleInitialize sebelum memanggil SHGetFileInfo.

Saat Anda menggunakan bendera SHGFI_EXETYPE dengan aplikasi Windows, versi Windows dari executable diberikan dalam HIWORD dari nilai pengembalian. Versi ini dikembalikan sebagai nilai heksadesimal. Untuk detail tentang menyamakan 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);

Nota

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

Syarat	Nilai
klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Platform Target	Windows
Header	shellapi.h
Pustaka	Shell32.lib
DLL	Shell32.dll (versi 4.0 atau yang lebih baru)

Lihat juga

FileIconInit

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2024-11-20