IMAPITable::SortTable
Область применения: Outlook 2013 | Outlook 2016
Метод IMAPITable::SortTable упорядочивает строки таблицы в зависимости от условий сортировки.
HRESULT SortTable(
LPSSortOrderSet lpSortCriteria,
ULONG ulFlags
);
Параметры
lpSortCriteria
[в] Указатель на структуру SSortOrderSet , содержащую применяемые критерии сортировки. Передача структуры SSortOrderSet , содержащей нулевые столбцы, означает, что таблица не должна отсортироваться в определенном порядке.
ulFlags
[в] Битовая маска флагов, управляющая временем операции IMAPITable::SortTable . Можно задать следующие флаги:
TBL_ASYNC
Запускает операцию асинхронно и возвращается до завершения операции.
TBL_BATCH
Откладывает завершение сортировки до тех пор, пока не потребуются данные в таблице.
Возвращаемое значение
S_OK
Операция сортировки прошла успешно.
MAPI_E_BUSY
Выполняется другая операция, которая предотвращает запуск операции сортировки. Либо выполняющиеся операции должны быть разрешены к завершению, либо она должна быть остановлена.
MAPI_E_NO_SUPPORT
Таблица не поддерживает запрошенный тип сортировки.
MAPI_E_TOO_COMPLEX
Таблица не может выполнить операцию, так как конкретные критерии сортировки, на которые указывает параметр lpSortCriteria , слишком сложны. SortTable может возвращать MAPI_E_TOO_COMPLEX при следующих условиях.
Операция сортировки запрашивается для столбца свойств, который реализация не может сортировать.
Реализация не поддерживает порядок сортировки, запрошенный в элементе ulOrder структуры SSortOrderSet .
Число отсортированных столбцов, указанное в элементе cSorts в SSortOrderSet, больше, чем может обработать реализация.
Операция сортировки запрашивается, как указано тегом свойства в SSortOrderSet, на основе свойства, которое отсутствует в доступном или активном наборе, и реализация не поддерживает сортировку по свойствам, отсутствуют в доступном наборе.
Одно свойство указывается несколько раз в наборе порядка сортировки, как указано в нескольких экземплярах одного тега свойства, и реализация не может выполнить такую операцию сортировки.
Операция сортировки на основе столбцов многозначных свойств запрашивается с помощью MVI_FLAG, а реализация не поддерживает сортировку по многозначным свойствам.
Тег свойства в SSortOrderSet указывает свойство или тип, который не поддерживается реализацией.
Операция сортировки, отличающаяся от операции сортировки, которая проходит через таблицу из свойства вперед PR_RENDERING_POSITION (PidTagRenderingPosition), указывается только для таблицы вложений, которая поддерживает этот тип сортировки.
Замечания
Метод IMAPITable::SortTable упорядочивает строки в табличном представлении. В то время как некоторые таблицы поддерживают как стандартную, так и категоризированную сортировку по различным ключевым столбцам сортировки, другие таблицы имеют более ограниченную поддержку. Поставщики адресных книг обычно не поддерживают сортировку таблиц. Поставщики хранилища сообщений обычно поддерживают сортировку до такой степени, что они сохраняют порядок сортировки папок, который возникает при сортировке полной таблицы (таблица без ограничений).
Некоторые таблицы позволяют выполнять сортировку по любому столбцу таблицы. Другие таблицы не выполняются; на столбцы, не включенные в табличное представление, вызов SortTable не влияет. Для некоторых таблиц требуется, чтобы ключи сортировки создавались только со столбцами в текущем наборе столбцов таблицы.
Таблица может возвращать MAPI_E_NO_SUPPORT или MAPI_E_TOO_COMPLEX из SortTable , если ей не удается завершить операцию сортировки. Кроме того, поставщики хранилищ не гарантируют соблюдение порядка сортировки, заданного для таблиц иерархии.
Если в структуре SSortOrderSet отсутствуют столбцы, на которые указывает параметр lpSortCriteria , таблица возвращает текущий набор столбцов. Текущий порядок сортировки можно получить, вызвав метод IMAPITable::QuerySortOrder таблицы.
Все закладки для таблицы становятся недействительными и должны быть удалены при вызове SortTable , а BOOKMARK_CURRENT закладка, указывающая текущее положение курсора, должна быть установлена в начале таблицы.
Если выполняется сортировка по столбцу, который содержит многозначное свойство без флага MVI_FLAG, значения столбца обрабатываются как полностью упорядоченный кортеж. Сравнение двух многозначных столбцов сравнивает элементы столбцов по порядку, сообщая о связи столбцов при первом неравенстве, и возвращает равенство только в том случае, если сравниваемые столбцы содержат одинаковые значения в том же порядке. Если один столбец содержит меньше значений, чем другой, то сообщаемое отношение равно значению NULL к другому значению.
Примечания для вызывающих методов
SortTable работает синхронно, если не задан один из флагов. Если задать флаг TBL_BATCH, SortTable отложит операцию сортировки, если вы не запросите данные. Если флаг TBL_ASYNC установлен, SortTable работает асинхронно, потенциально возвращая его до завершения операции.
Вызовите метод IMAPITable::Abort , чтобы остановить асинхронную операцию, если сортировка должна быть выполнена немедленно. Если команда SortTable не может продолжить работу из-за выполнения одной или нескольких асинхронных операций с таблицей, она возвращает MAPI_E_BUSY.
Чтобы повысить производительность, вызовите Метод SetColumns , чтобы настроить набор столбцов таблицы, и Ограничить , чтобы ограничить количество строк в таблице перед вызовом SortTable для выполнения сортировки.
При сбое SortTable порядок сортировки, действовав до сбоя, по-прежнему действует.