Metode IShellFolder::CompareIDs (shobjidl_core.h)

Artikel
03/09/2024

Menentukan urutan relatif dari dua objek atau folder file, mengingat daftar pengidentifikasi itemnya.

Sintaks

HRESULT CompareIDs(
  [in] LPARAM             lParam,
  [in] PCUIDLIST_RELATIVE pidl1,
  [in] PCUIDLIST_RELATIVE pidl2
);

Parameter

[in] lParam

Jenis: LPARAM

Nilai yang menentukan bagaimana perbandingan harus dilakukan.

Enam belas bit lParam yang lebih rendah menentukan aturan pengurutan. Sebagian besar aplikasi mengatur aturan pengurutan ke nilai default nol, yang menunjukkan bahwa dua item harus dibandingkan dengan nama. Sistem tidak mendefinisikan aturan pengurutan lainnya. Beberapa objek folder mungkin memungkinkan aplikasi panggilan untuk menggunakan enam belas bit lParam yang lebih rendah untuk menentukan aturan pengurutan khusus folder. Aturan dan nilai lParam terkait ditentukan oleh folder .

Ketika objek tampilan folder sistem memanggil IShellFolder::CompareIDs, enam belas bit lParam yang lebih rendah digunakan untuk menentukan kolom yang akan digunakan untuk perbandingan.

Enam belas bit atas lParam digunakan untuk bendera yang memodifikasi aturan pengurutan. Sistem saat ini mendefinisikan bendera pengubah ini.

SHCIDS_ALLFIELDS

Versi 5.0. Bandingkan semua informasi yang terkandung dalam struktur ITEMIDLIST , bukan hanya nama tampilan. Bendera ini hanya berlaku untuk objek folder yang mendukung antarmuka IShellFolder2 . Misalnya, jika dua item tersebut adalah file, folder harus membandingkan nama, ukuran, waktu file, atribut, dan informasi lainnya dalam struktur. Jika bendera ini diatur, enam belas bit lParam yang lebih rendah harus nol.

SHCIDS_CANONICALONLY

Versi 5.0. Saat membandingkan berdasarkan nama, bandingkan nama sistem tetapi bukan nama tampilan. Ketika bendera ini diteruskan, dua item dibandingkan dengan kriteria apa pun yang ditentukan folder Shell paling efisien, selama mengimplementasikan fungsi pengurutan yang konsisten. Bendera ini berguna saat membandingkan kesetaraan atau ketika hasil pengurutan tidak ditampilkan kepada pengguna. Bendera ini tidak dapat digabungkan dengan bendera lain.

[in] pidl1

Jenis: PCUIDLIST_RELATIVE

Penunjuk ke struktur ITEMIDLIST item pertama. Ini akan relatif terhadap folder. Struktur ITEMIDLIST ini dapat berisi lebih dari satu elemen; oleh karena itu, seluruh struktur harus dibandingkan, bukan hanya elemen pertama.

[in] pidl2

Jenis: PCUIDLIST_RELATIVE

Penunjuk ke struktur ITEMIDLIST item kedua. Ini akan relatif terhadap folder. Struktur ITEMIDLIST ini dapat berisi lebih dari satu elemen; oleh karena itu, seluruh struktur harus dibandingkan, bukan hanya elemen pertama.

Mengembalikan nilai

Jenis: HRESULT

Jika metode ini berhasil, bidang CODE HRESULT berisi salah satu nilai berikut. Untuk informasi mengenai ekstraksi bidang CODE dari HRESULT yang dikembalikan, lihat Keterangan. Jika metode ini tidak berhasil, metode ini mengembalikan kode kesalahan COM.

Menampilkan kode	Deskripsi
Negatif	Nilai pengembalian negatif menunjukkan bahwa item pertama harus mendahului yang kedua (pidl1 < pidl2).
Positif	Nilai pengembalian positif menunjukkan bahwa item pertama harus mengikuti yang kedua (pidl1 > pidl2).
Nol	Nilai pengembalian nol menunjukkan bahwa dua item sama (pidl1 = pidl2).

Keterangan

Catatan untuk Aplikasi Panggilan

Jangan atur bendera SHCIDS_ALLFIELDS di lParam jika objek folder tidak mendukung IShellFolder2. Melakukannya mungkin memiliki hasil yang tidak dapat diprediksi. Jika Anda menggunakan bendera SHCIDS_ALLFIELDS , enam belas bit lParam yang lebih rendah harus diatur ke nol.

Gunakan makro HRESULT_CODE untuk mengekstrak bidang CODE dari HRESULT, lalu transmisikan hasilnya sebagai singkat.

HRESULT hres = psf->CompareIDs(lParam, pidl1, pidl2);
if ((short)HRESULT_CODE(hres) < 0)
   { /* pidl1 comes first */ }
else if ((short)HRESULT_CODE(hres) > 0) 
   { /* pidl2 comes first */ }
else 
   { /* the two pidls are equal */ }

Catatan untuk Pelaksana

Untuk mengekstrak aturan pengurutan, gunakan operator AND bitwise (&) untuk menggabungkan lParam dengan SHCIDS_COLUMNMASK (0X0000FFFF). Operasi ini menutupi enam belas bit atas lParam, termasuk nilai SHCIDS_ALLFIELDS .

Makro MAKE_HRESULT berguna untuk membangun nilai pengembalian untuk implementasi metode CompareIDs. Contohnya:

HRESULT CompareIDs(LPARAM lParam, PCUIDLIST_RELATIVE pidl1, PCUIDLIST_RELATIVE pidl2)
{
    short sResult;
    unsigned uSeverity = 0x000000000;
    
    // Code that determines the relative order of pidl1 and pidl2 according to
    // any sorting rules specified by lParam goes here.
    //
    // Set sResult = -1 if pidl1 precedes pidl2 (pidl1 < pidl2).
    // Set sResult =  1 if pidl1 follows pidl2. (pidl1 > pidl2).
    // Set sResult =  0 if pidl1 and pidl2 are equivalent in terms of ordering. (pidl1 = pidl2).
    //
    // Leave uSeverity = 0 if the order is successfully determined.
    // Set uSeverity = 0x00000001 if there is an error.

    return MAKE_HRESULT(uSeverity, 0, (unsigned short)sResult);
}

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

Share via