Metode IShellFolder::GetDisplayNameOf (shobjidl_core.h)

Artikel
08/26/2023

Mengambil nama tampilan untuk objek file atau subfolder yang ditentukan.

Sintaks

HRESULT GetDisplayNameOf(
  [in]  PCUITEMID_CHILD pidl,
  [in]  SHGDNF          uFlags,
  [out] STRRET          *pName
);

Parameter

[in] pidl

Jenis: PCUITEMID_CHILD

PIDL yang secara unik mengidentifikasi objek file atau subfolder relatif terhadap folder induk.

[in] uFlags

Jenis: SHGDNF

Bendera yang digunakan untuk meminta jenis nama tampilan yang akan dikembalikan. Untuk daftar nilai yang mungkin, lihat jenis enumerasi SHGDNF .

[out] pName

Jenis: STRRET*

Ketika metode ini kembali, berisi penunjuk ke struktur STRRET untuk mengembalikan nama tampilan. Jenis nama yang dikembalikan dalam struktur ini dapat berupa jenis yang diminta, tetapi folder Shell mungkin mengembalikan jenis yang berbeda.

Nilai kembali

Jenis: HRESULT

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

Keterangan

Adalah tanggung jawab pemanggil untuk membebaskan sumber daya yang dialokasikan oleh fungsi ini.

Biasanya, pidl hanya dapat merujuk ke item yang dimuat oleh folder induk. PIDL harus tingkat tunggal dan berisi tepat satu struktur SHITEMID diikuti dengan nol yang mengakhiri. Jika Anda ingin mengambil nama tampilan item yang lebih dalam dari satu tingkat jauh dari folder induk, gunakan SHBindToParent untuk mengikat dengan folder induk langsung item lalu meneruskan PIDL tingkat tunggal item ke IShellFolder::GetDisplayNameOf.

Selain itu, jika bendera SHGDN_FORPARSING diatur dalam uFlags dan bendera SHGDN_INFOLDER tidak diatur, pidl dapat merujuk ke objek pada tingkat apa pun di bawah folder induk dalam hierarki namespace. Pada satu waktu, pidl bisa menjadi PIDL multitingkat, relatif terhadap folder induk, dan dapat berisi beberapa struktur SHITEMID . Namun, ini tidak lagi didukung dan pidl sekarang hanya boleh merujuk ke satu item anak.

Cara paling sederhana untuk mengambil nama tampilan dari struktur yang diarahkan oleh pName adalah dengan meneruskannya ke StrRetToBuf atau StrRetToStr. Fungsi-fungsi ini mengambil struktur STRRET dan mengembalikan nama. Anda juga dapat memeriksa anggota uType struktur, dan mengambil nama dari anggota yang sesuai.

Bendera yang ditentukan dalam uFlags adalah petunjuk tentang penggunaan nama yang dimaksudkan. Mereka tidak menjamin bahwa IShellFolder akan mengembalikan bentuk nama yang diminta. Jika formulir tersebut tidak tersedia, formulir lain mungkin dikembalikan. Secara khusus, tidak ada jaminan bahwa nama yang dikembalikan oleh bendera SHGDN_FORPARSING akan berhasil diurai oleh IShellFolder::P arseDisplayName. Ada juga beberapa kombinasi bendera yang dapat menyebabkan perjalanan pulang pergi GetDisplayNameOf/ParseDisplayName tidak mengembalikan daftar pengidentifikasi asli. Kejadian ini luar biasa, tetapi Anda harus memeriksa untuk memastikannya.

Catatan Nama penguraian yang dikembalikan ketika uFlags memiliki set bendera SHGDN_FORPARSING belum tentu merupakan string teks normal. Folder virtual seperti Komputer Saya mungkin mengembalikan string yang berisi GUID objek folder dalam formulir "::{GUID}". Pengembang yang mengimplementasikan IShellFolder::GetDisplayNameOf didorong untuk mengembalikan nama penguraian yang sedekat mungkin dengan nama tampilan, karena pengguna akhir sering kali perlu mengetik atau mengedit nama-nama ini.

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

Lihat juga

IShellFolder

IShellFolder2

Bagikan melalui