IShellFolder：：CompareIDs 方法 (shobjidl_core.h)

项目
01/10/2024

确定给定两个文件对象或文件夹的项标识符列表的相对顺序。

语法

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

参数

[in] lParam

类型：LPARAM

一个值，该值指定应如何执行比较。

lParam 的下 16 位定义排序规则。大多数应用程序将排序规则设置为默认值零，指示应按名称比较这两项。系统不定义任何其他排序规则。某些文件夹对象可能允许调用应用程序使用 lParam 的低 16 位来指定特定于文件夹的排序规则。规则及其关联的 lParam 值由文件夹定义。

当系统文件夹视图对象调用 IShellFolder：：CompareIDs 时， lParam 的下 16 位用于指定要用于比较的列。

lParam 的上 16 位用于修改排序规则的标志。系统当前定义这些修饰符标志。

SHCIDS_ALLFIELDS

版本 5.0。比较 ITEMIDLIST 结构中包含的所有信息，而不仅仅是显示名称。此标志仅对支持 IShellFolder2 接口的文件夹对象有效。例如，如果这两项是文件，则文件夹应比较其名称、大小、文件时间、属性以及结构中的任何其他信息。如果设置了此标志， 则 lParam 的下 16 位必须为零。

SHCIDS_CANONICALONLY

版本 5.0。按名称比较时，请比较系统名称，而不是显示名称。传递此标志时，只要 Shell 文件夹实现一致的排序函数，将按照 Shell 文件夹确定最有效的任何条件来比较这两个项。当比较是否相等或未向用户显示排序结果时，此标志非常有用。此标志不能与其他标志组合使用。

[in] pidl1

类型： PCUIDLIST_RELATIVE

指向第一项的 ITEMIDLIST 结构的指针。它将相对于文件夹。此 ITEMIDLIST 结构可以包含多个元素;因此，必须比较整个结构，而不仅仅是第一个元素。

[in] pidl2

类型： PCUIDLIST_RELATIVE

指向第二项的 ITEMIDLIST 结构的指针。它将相对于文件夹。此 ITEMIDLIST 结构可以包含多个元素;因此，必须比较整个结构，而不仅仅是第一个元素。

返回值

类型： HRESULT

如果此方法成功，则 HRESULT 的 CODE 字段包含以下值之一。有关从返回的 HRESULT 中提取 CODE 字段的信息，请参阅备注。如果此方法不成功，则返回 COM 错误代码。

返回代码	说明
负	负返回值指示第一项应位于第二个 (pidl1 < pidl2) 之前。
正	正返回值指示第一项应遵循第二个 (pidl1 > pidl2) 。
Zero	返回值零表示这两个项是相同的 (pidl1 = pidl2) 。

注解

呼叫应用程序注意事项

如果文件夹对象不支持 IShellFolder2，请不要在 lParam 中设置SHCIDS_ALLFIELDS标志。这样做可能会产生不可预知的结果。如果使用 SHCIDS_ALLFIELDS 标志，则必须将 lParam 的下 16 位设置为零。

使用 HRESULT_CODE 宏从 HRESULT 中提取 CODE 字段，然后将结果强制转换为 short。

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 的上 16 位，包括 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