IMAPITable::FindRow
Область применения: Outlook 2013 | Outlook 2016
Находит следующую строку в таблице, которая соответствует определенным условиям поиска, и перемещает курсор в нее.
HRESULT FindRow(
LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
);
Параметры
lpRestriction
[в] Указатель на структуру SRestriction , которая описывает критерии поиска.
BkOrigin
[в] Закладка, определяющая строку, в которой должен начаться поиск FindRow . Закладку можно создать с помощью метода IMAPITable::CreateBookmark или передать одно из следующих предопределенных значений.
BOOKMARK_BEGINNING
Выполняет поиск в начале таблицы.
BOOKMARK_CURRENT
Выполняет поиск из строки в таблице, в которой находится курсор.
BOOKMARK_END
Выполняет поиск в конце таблицы.
ulFlags
[в] Битовая маска флагов, управляющая направлением поиска. Можно задать следующий флаг:
DIR_BACKWARD
Выполняет поиск в обратном направлении из строки, определенной закладкой.
Возвращаемое значение
S_OK
Операция поиска прошла успешно.
MAPI_E_INVALID_BOOKMARK
Закладка в параметре BkOrigin недопустима, так как она удалена или находится за пределами последней запрошенной строки.
MAPI_E_NOT_FOUND
Строк, соответствующих ограничению, не найдено.
MAPI_W_POSITION_CHANGED
Вызов выполнен успешно, но закладка, используемая в операции, больше не задается в той же строке, что и при последнем использовании. Если закладка не использовалась, она больше не находится в том же положении, что и при ее создании. При возврате этого предупреждения вызов должен быть обработан как успешный. Чтобы проверить наличие этого предупреждения, используйте макрос HR_FAILED . См . раздел Использование макросов для обработки ошибок.
Замечания
Метод IMAPITable::FindRow находит первую строку в таблице, которая соответствует набору условий поиска, описанных в структуре SRestriction , на которую указывает параметр lpRestriction .
Обычно FindRow выполняет поиск вперед из указанной закладки. Вызывающий объект может настроить поиск для перемещения назад от закладки, задав флаг DIR_BACKWARD в параметре ulFlags . Поиск вперед начинается с текущей закладки; поиск в обратном направлении начинается со строки перед закладкой. Конечная позиция поиска находится непосредственно перед первой строкой, удовлетворяющей ограничению.
Если строка, на которую указывает закладка в параметре BkOrigin , больше не существует в таблице и таблица не может установить новую позицию для закладки, функция FindRow возвращает MAPI_E_INVALID_BOOKMARK. Если строка, на которую указывает BkOrigin , больше не существует и таблица может установить новую позицию для закладки, FindRow возвращает MAPI_W_POSITION_CHANGED.
Если закладка, переданная в BkOrigin , BOOKMARK_BEGINNING или BOOKMARK_END, функция FindRow возвращает MAPI_E_NOT_FOUND, если соответствующая строка не найдена. Если закладка, используемая в BkOrigin , BOOKMARK_CURRENT, FindRow может возвращать MAPI_W_POSITION_CHANGED, но не MAPI_E_INVALID_BOOKMARK, так как всегда имеется текущее положение курсора.
Столбец свойств PR_INSTANCE_KEY (PidTagInstanceKey) является обязательным для всех таблиц, а все реализации FindRow необходимы для поддержки вызовов, ищущих строку на основе PR_INSTANCE_KEY.
Примечания для исполнителей
Тип поиска префиксов, выполняемый FindRow , полезен только в том случае, если поиск выполняется в том же направлении, что и в организации таблицы. Чтобы добиться требуемого поведения, функция сравнения, подразумеваемая RELOP_GE передается в структуре ограничения свойств, должна быть той же функцией сравнения, на которой основан порядок сортировки таблицы.
Примечания для вызывающих методов
FindRow можно использовать для поддержки прокрутки на основе строк, введенных пользователем, особенно в списках в диалоговых окнах адресов. При таком типе прокрутки пользователи вводят постепенно более длинные префиксы требуемого строкового значения, и вы можете периодически выполнять вызов FindRow , чтобы перейти к первой строке, которая соответствует префиксу. Направление перехода курсора зависит от того, в каком направлении будет выполнен поиск.
Чтобы использовать FindRow, необходимо задать закладку. Строковый поиск может происходить из любой закладки, в том числе из предустановленных закладок, указывающих текущее положение, начало и конец таблицы. Если в таблице имеется большое количество строк, операция поиска может выполняться медленно.
Используйте ограничение, чтобы найти префикс строки для прокрутки, как показано ниже. Для прямого поиска по столбцу, отсортированного по возрастанию, и для обратного поиска по столбцу, отсортированного в порядке убывания, передайте структуру ограничения свойств в параметре lpRestriction с отношением RELOP_GE и соответствующим тегом свойства и префиксом свойства с помощью префиксаGEтега форматирования.
Дополнительные сведения об использовании структур ограничений для указания фильтра см. в разделе Об ограничениях.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
MFCMAPI использует метод IMAPITable::FindRow для поиска строк, соответствующих ограничению. |