Metode IShellFolder::P arseDisplayName (shobjidl_core.h)

Artikel
03/15/2023

Menerjemahkan nama tampilan objek file atau folder ke dalam daftar pengidentifikasi item.

Sintaks

HRESULT ParseDisplayName(
  [in]      HWND             hwnd,
  [in]      IBindCtx         *pbc,
  [in]      LPWSTR           pszDisplayName,
  [out]     ULONG            *pchEaten,
  [out]     PIDLIST_RELATIVE *ppidl,
  [in, out] ULONG            *pdwAttributes
);

Parameter

[in] hwnd

Jenis: HWND

Handel jendela. Klien harus menyediakan handel jendela jika menampilkan kotak dialog atau pesan. Jika tidak, atur hwnd ke NULL.

[in] pbc

Jenis: IBindCtx*

Pilihan. Penunjuk ke konteks ikatan yang digunakan untuk meneruskan parameter sebagai input dan output ke fungsi penguraian. Parameter yang diteruskan ini sering kali khusus untuk sumber data dan didokumenkan oleh pemilik sumber data. Misalnya, sumber data sistem file menerima nama yang diurai (sebagai struktur WIN32_FIND_DATA ), menggunakan parameter konteks ikat STR_FILE_SYS_BIND_DATA . STR_PARSE_PREFER_FOLDER_BROWSING dapat diteruskan untuk menunjukkan bahwa URL diurai menggunakan sumber data sistem file jika memungkinkan. Buat objek konteks ikat menggunakan CreateBindCtx dan isi nilai menggunakan IBindCtx::RegisterObjectParam. Lihat Mengikat Kunci String Konteks untuk daftar lengkapnya.

Jika tidak ada data yang diteruskan ke atau diterima dari fungsi penguraian, nilai ini bisa null.

[in] pszDisplayName

Jenis: LPWSTR

String Unicode yang dihentikan null dengan nama tampilan. Karena setiap folder Shell mendefinisikan sintaks penguraiannya sendiri, bentuk yang dapat diambil string ini dapat bervariasi. Folder desktop, misalnya, menerima jalur seperti "C:\My Docs\My File.txt". Ini juga akan menerima referensi ke item di namespace layanan yang memiliki GUID yang terkait dengannya menggunakan sintaks "::{GUID}". Misalnya, untuk mengambil daftar pengidentifikasi yang sepenuhnya memenuhi syarat untuk panel kontrol dari folder desktop, Anda dapat menggunakan yang berikut ini:

::{CLSID for Control Panel}\::{CLSID for printers folder}

[out] pchEaten

Jenis: ULONG*

Penunjuk ke nilai ULONG yang menerima jumlah karakter nama tampilan yang diurai. Jika aplikasi Anda tidak memerlukan informasi ini, atur pchEaten ke NULL, dan tidak ada nilai yang akan dikembalikan.

[out] ppidl

Jenis: PIDLIST_RELATIVE*

Ketika metode ini kembali, berisi penunjuk ke PIDL untuk objek . Daftar pengidentifikasi item yang dikembalikan menentukan item relatif terhadap folder penguraian. Jika objek yang terkait dengan pszDisplayName berada dalam folder penguraian, daftar pengidentifikasi item yang dikembalikan hanya akan berisi satu struktur SHITEMID . Jika objek berada dalam subfolder folder penguraian, daftar pengidentifikasi item yang dikembalikan akan berisi beberapa struktur SHITEMID . Jika terjadi kesalahan, NULL dikembalikan dalam alamat ini.

Ketika tidak lagi diperlukan, pemanggil bertanggung jawab untuk membebaskan sumber daya ini dengan memanggil CoTaskMemFree.

[in, out] pdwAttributes

Jenis: ULONG*

Nilai yang digunakan untuk mengkueri atribut file. Jika tidak digunakan, harus diatur ke NULL. Untuk mengkueri satu atau beberapa atribut, inisialisasi parameter ini dengan bendera SFGAO yang mewakili atribut yang menarik. Saat dikembalikan, atribut yang benar dan diminta akan ditetapkan.

Nilai kembali

Jenis: HRESULT

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

Keterangan

Beberapa folder Shell mungkin tidak mengimplementasikan IShellFolder::P arseDisplayName. Setiap folder yang memang akan menentukan sintaks penguraiannya sendiri.

ParseDisplayName tidak diharapkan untuk menangani jalur relatif atau indikator folder induk ("." atau ".."). Terserah pemanggil untuk menghapus ini dengan tepat.

Jangan gunakan bendera SFGAO_VALIDATE di pdwAttributes untuk memverifikasi keberadaan item yang namanya sedang diurai. IShellFolder::P arseDisplayName secara implisit memvalidasi keberadaan item kecuali perilaku tersebut ditimpa oleh parameter konteks ikatan khusus.

Mengkueri beberapa atribut mungkin relatif lambat dan menggunakan memori dalam jumlah yang signifikan. Misalnya, untuk menentukan apakah file dibagikan, Shell akan memuat komponen jaringan. Prosedur ini mungkin memerlukan pemuatan beberapa DLL. Tujuan pdwAttributes adalah untuk memungkinkan Anda membatasi kueri hanya untuk informasi yang diperlukan. Fragmen kode berikut menggambarkan cara mengetahui apakah file dikompresi.

LPITEMIDLIST pidl;
ULONG cbEaten;
DWORD dwAttribs = SFGAO_COMPRESSED;

hres = psf->ParseDisplayName(NULL,
                             NULL,
                             lpwszDisplayName,
                             &cbEaten,  // This can be NULL
                             &pidl,
                             &dwAttribs);

if(dwAttribs & SFGAO_COMPRESSED)
{
    // Do something with the compressed file
}

Karena pdwAttributes adalah parameter masuk/keluar, pdwAttributes harus selalu diinisialisasi. Jika Anda meneruskan nilai yang tidak diinisialisasi, beberapa bit mungkin secara tidak sengaja diatur. IShellFolder::P arseDisplayName kemudian akan meminta atribut yang sesuai, yang dapat menyebabkan penundaan atau permintaan memori yang tidak diinginkan. Jika Anda tidak ingin mengkueri atribut, atur pdwAttributes ke NULL untuk menghindari perilaku yang tidak dapat diprediksi.

Metode ini mirip dengan metode IParseDisplayName::P arseDisplayName .

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

IShellFolder::GetAttributesOf

IShellLink

Bagikan melalui