IShellFolder：：CompareIDs 方法 (shobjidl_core.h)

發行項
03/02/2024

決定兩個檔案物件或資料夾的相對順序，指定其專案識別符清單。

語法

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

參數

[in] lParam

類型： LPARAM

值，指定應該如何執行比較。

lParam 的下十六位會定義排序規則。大部分的應用程式會將排序規則設定為預設值零，表示應該依名稱比較這兩個專案。系統不會定義任何其他排序規則。某些資料夾物件可能會允許呼叫應用程式使用 lParam 的下十六位來指定資料夾特定的排序規則。規則及其相關聯的 lParam 值是由資料夾所定義。

當系統資料夾檢視物件呼叫 IShellFolder：：CompareIDs 時， 會使用 lParam 的下十六位來指定要用於比較的數據行。

lParam 的上十六位會用於修改排序規則的旗標。系統目前會定義這些修飾詞旗標。

SHCIDS_ALLFIELDS

5.0 版。比較 ITEMIDLIST 結構中包含的所有資訊，而不只是顯示名稱。此旗標僅適用於支援 IShellFolder2 介面的資料夾物件。例如，如果兩個專案是檔案，資料夾應該比較其名稱、大小、檔案時間、屬性，以及結構中的其他任何資訊。如果設定此旗標， lParam 的下十六位必須是零。

SHCIDS_CANONICALONLY

5.0 版。依名稱比較時，請比較系統名稱，但不會比較顯示名稱。傳遞此旗標時，只要它實作一致的排序函式，Shell 資料夾決定的任何準則都會比較這兩個專案最有效率。當比較相等或未向用戶顯示排序結果時，此旗標很有用。此旗標無法與其他旗標結合。

[in] pidl1

類型： PCUIDLIST_RELATIVE

第一個專案 ITEMIDLIST 結構的指標。它將會相對於資料夾。這個 ITEMIDLIST 結構可以包含多個元素;因此，必須比較整個結構，而不只是第一個專案。

[in] pidl2

類型： PCUIDLIST_RELATIVE

第二個專案 ITEMIDLIST 結構的指標。它將會相對於資料夾。這個 ITEMIDLIST 結構可以包含多個元素;因此，必須比較整個結構，而不只是第一個專案。

傳回值

類型： HRESULT

如果此方法成功， HRESULT 的 CODE 欄位會包含下列其中一個值。如需從傳回 的 HRESULT 擷取 CODE 欄位的相關信息，請參閱。如果此方法不成功，則會傳回 COM 錯誤碼。

傳回碼	Description
負	負傳回值表示第二個項目應該在第二個 (pidl1 < pidl2) 之前。
正面	正傳回值表示第二個項目應該遵循第二個 (pidl1 > pidl2) 。
Zero	零的傳回值表示這兩個專案 (pidl1 = pidl2) 相同。

備註

呼叫應用程式注意事項

如果資料夾物件不支援 IShellFolder2，請勿在 lParam 中設定SHCIDS_ALLFIELDS旗標。這麼做可能會有無法預測的結果。如果您使用 SHCIDS_ALLFIELDS 旗標， lParam 的下十六位必須設定為零。

使用 HRESULT_CODE 宏從 HRESULT 擷取 CODE 欄位，然後將結果轉換成簡短結果。

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 */ }

實作者注意事項

若要擷取排序規則，請使用位AND運算元 (&) 來結合 lParam 與SHCIDS_COLUMNMASK (0X0000FFFF) 。此作業會遮罩 lParam 的上十六位，包括 SHCIDS_ALLFIELDS 值。

MAKE_HRESULT宏適用於建構 CompareIDs 方法實作的傳回值。例如：

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);
}

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	shobjidl_core.h (包括 Shobjidl.h)
Dll	Shell32.dll (4.0 版或更新版本)

另請參閱

IShellFolder

IShellFolder2

共用方式為