Metode IExtractIconA::GetIconLocation (shlobj_core.h)

Artikel
08/26/2023

Mendapatkan lokasi dan indeks ikon.

Sintaks

HRESULT GetIconLocation(
        UINT uFlags,
  [out] PSTR pszIconFile,
        UINT cchMax,
  [out] int  *piIndex,
  [out] UINT *pwFlags
);

Parameter

uFlags

Jenis: UINT

Satu atau beberapa nilai berikut ini. Parameter ini juga bisa NULL.

GIL_ASYNC (0x0020)

Atur bendera ini untuk menentukan apakah ikon harus diekstraksi secara asinkron. Jika ikon dapat diekstraksi dengan cepat, bendera ini biasanya diabaikan. Jika ekstraksi akan memakan waktu lebih lama, GetIconLocation harus mengembalikan E_PENDING. Lihat Komentar untuk diskusi lebih lanjut.

GIL_DEFAULTICON (0x0040)

Ambil informasi tentang ikon fallback. Ikon fallback biasanya digunakan saat ikon yang diinginkan diekstraksi dan ditambahkan ke cache.

GIL_FORSHELL (0x0002)

Ikon ditampilkan dalam folder Shell.

GIL_FORSHORTCUT (0x0080)

Ikon menunjukkan pintasan. Namun, ekstraktor ikon tidak boleh menerapkan overlay pintasan; yang akan dilakukan nanti. Ikon pintasan tidak bergantung pada status.

GIL_OPENICON (0x0001)

Ikon berada dalam status terbuka jika gambar status terbuka dan status tertutup tersedia. Jika bendera ini tidak ditentukan, ikon berada dalam status normal atau tertutup. Bendera ini biasanya digunakan untuk objek folder.

GIL_CHECKSHIELD (0x0200)

Secara eksplisit mengembalikan GIL_SHIELD atau GIL_FORCENOSHIELD dalam pwFlags. Jangan blokir jika GIL_ASYNC diatur.

[out] pszIconFile

Jenis: PTSTR

Penunjuk ke buffer yang menerima lokasi ikon. Lokasi ikon adalah string yang dihentikan null yang mengidentifikasi file yang berisi ikon.

cchMax

Jenis: UINT

Ukuran buffer, dalam karakter, diacu oleh pszIconFile.

[out] piIndex

Jenis: int*

Penunjuk ke int yang menerima indeks ikon dalam file yang ditujukan oleh pszIconFile.

[out] pwFlags

Jenis: UINT*

Penunjuk ke nilai UINT yang menerima nol atau kombinasi dari nilai berikut.

GIL_DONTCACHE (0x0010)

Bit gambar fisik untuk ikon ini tidak di-cache oleh aplikasi panggilan.

GIL_NOTFILENAME (0x0008)

Lokasi bukan nama file/pasangan indeks. Nilai dalam pszIconFile dan piIndex tidak dapat diteruskan ke ExtractIcon atau ExtractIconEx.

Ketika bendera ini dihilangkan, nilai yang dikembalikan dalam pszIconFile adalah nama jalur yang sepenuhnya memenuhi syarat untuk file .ico atau ke file yang dapat berisi ikon. Selain itu, nilai yang dikembalikan dalam piIndex adalah indeks ke dalam file yang mengidentifikasi ikon mana yang akan digunakan. Oleh karena itu, ketika bendera GIL_NOTFILENAME dihilangkan, nilai-nilai ini dapat diteruskan ke ExtractIcon atau ExtractIconEx.

GIL_PERCLASS (0x0004)

Semua objek kelas ini memiliki ikon yang sama. Bendera ini digunakan secara internal oleh Shell. Implementasi umum IExtractIcon tidak memerlukan bendera ini karena bendera menyiratkan bahwa handler ikon tidak diperlukan untuk menyelesaikan ikon berdasarkan per objek. Metode yang direkomendasikan untuk menerapkan ikon per kelas adalah mendaftarkan DefaultIcon untuk kelas .

GIL_PERINSTANCE (0x0002)

Setiap objek kelas ini memiliki ikonnya sendiri. Bendera ini digunakan secara internal oleh Shell untuk menangani kasus seperti Setup.exe, di mana objek dengan nama yang identik dapat memiliki ikon yang berbeda. Implementasi umum IExtractIcon tidak memerlukan bendera ini.

GIL_SIMULATEDOC (0x0001)

Aplikasi panggilan harus membuat ikon dokumen menggunakan ikon yang ditentukan.

GIL_SHIELD (0x0200)

Hanya Windows Vista. Aplikasi panggilan harus memberi stempel ikon dengan perisai UAC.

GIL_FORCENOSHIELD (0x0400)

Hanya Windows Vista. Aplikasi panggilan tidak boleh memberi stempel ikon dengan perisai UAC.

Nilai kembali

Jenis: HRESULT

Mengembalikan S_OK jika fungsi mengembalikan lokasi yang valid, atau S_FALSE jika Shell harus menggunakan ikon default. Jika bendera GIL_ASYNC diatur dalam uFlags, metode dapat mengembalikan E_PENDING untuk menunjukkan bahwa ekstraksi ikon akan memakan waktu.

Keterangan

Ketika klien menetapkan bendera GIL_ASYNC di uFlags dan menerima E_PENDING sebagai nilai pengembalian, biasanya membuat utas latar belakang untuk mengekstrak ikon. Ini memanggil GetIconLocation dari utas itu, tanpa bendera GIL_ASYNC , untuk mengambil lokasi ikon. Kemudian memanggil IExtractIcon::Extract untuk mengekstrak ikon. Mengembalikan E_PENDING menyiratkan bahwa objek bebas utas. Dengan kata lain, dapat dengan aman dipanggil secara bersamaan oleh beberapa utas.

Bendera GIL_DEFAULTICON biasanya diatur dalam kasus di mana ikon yang diinginkan ditemukan, tetapi ikon tersebut tidak ada di cache ikon. Ekstraksi ikon adalah proses latar belakang prioritas rendah, dan karenanya mungkin tertunda oleh proses lain. Ikon default akan ditampilkan sebagai pengganti ikon akhir selama waktu yang diperlukan agar ikon akhir tersebut diekstraksi, ditambahkan ke cache, dan tersedia.

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	shlobj_core.h
DLL	Shell32.dll (versi 4.0 atau yang lebih baru)

Bagikan melalui