Метод IShellFolder::CompareIDs (shobjidl_core.h)

Статья
08/26/2023

Определяет относительный порядок двух файловых объектов или папок с учетом их списков идентификаторов элементов.

Синтаксис

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. При сравнении по имени сравните системные имена, но не отображаемые имена. При передаче этого флага два элемента сравниваются по тем критериям, которые папка оболочки определяет, являются наиболее эффективными при условии, что в ней реализована согласованная функция сортировки. Этот флаг полезен при сравнении на равенство или когда результаты сортировки не отображаются для пользователя. Этот флаг нельзя сочетать с другими флагами.

[in] pidl1

Тип: PCUIDLIST_RELATIVE

Указатель на структуру ITEMIDLIST первого элемента. Он будет относительно папки. Эта структура ITEMIDLIST может содержать несколько элементов; поэтому необходимо сравнивать всю структуру, а не только первый элемент.

[in] pidl2

Тип: PCUIDLIST_RELATIVE

Указатель на структуру ITEMIDLIST второго элемента. Он будет относительно папки. Эта структура ITEMIDLIST может содержать несколько элементов; поэтому необходимо сравнивать всю структуру, а не только первый элемент.

Возвращаемое значение

Тип: HRESULT

Если этот метод выполнен успешно, поле КОД HRESULT содержит одно из следующих значений. Сведения об извлечении поля CODE из возвращаемого объекта HRESULT см. в разделе Примечания. Если этот метод завершается неудачно, он возвращает код com-ошибки.

Код возврата	Описание
Отрицательные	Отрицательное возвращаемое значение указывает, что первый элемент должен предшествовать второму (pidl1 < pidl2).
Положительные	Положительное возвращаемое значение указывает, что первый элемент должен следовать за вторым (pidl1 > pidl2).
Нуль	Возвращаемое нулевое значение указывает, что два элемента одинаковы (pidl1 = pidl2).

Не устанавливайте флаг SHCIDS_ALLFIELDS в lParam , если объект folder не поддерживает IShellFolder2. Это может привести к непредсказуемым результатам. Если вы используете флаг SHCIDS_ALLFIELDS , для нижних шестнадцати битов lParam необходимо задать нулевое значение.

Используйте макрос HRESULT_CODE, чтобы извлечь поле CODE из HRESULT, а затем привести результат в виде короткого.

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
Header	shobjidl_core.h (включая Shobjidl.h)
DLL	Shell32.dll (версия 4.0 или более поздняя)

См. также раздел

IShellFolder

IShellFolder2