IMAPITable::SeekRow
Область применения: Outlook 2013 | Outlook 2016
Перемещает курсор в определенную позицию в таблице.
HRESULT SeekRow(
BOOKMARK bkOrigin,
LONG lRowCount,
LONG FAR * lplRowsSought
);
Параметры
bkOrigin
[в] Закладка, определяющая начальную позицию для операции поиска. Закладку можно создать с помощью метода IMAPITable::CreateBookmark или передать одно из следующих предопределенных значений.
BOOKMARK_BEGINNING
Запускает операцию поиска с начала таблицы.
BOOKMARK_CURRENT
Запускает операцию поиска из строки таблицы, в которой находится курсор.
BOOKMARK_END
Запускает операцию поиска с конца таблицы.
lRowCount
[в] Число строк для перемещения со знаком, начиная с закладки, определяемой параметром bkOrigin .
lplRowsSought
[out] Если lRowCount является допустимым указателем на входные данные, lplRowsSought указывает на количество строк, обработанных в операции поиска, знак которого указывает направление поиска вперед или назад. Если значение lRowCount является отрицательным, то значение lplRowsSought — отрицательное.
Возвращаемое значение
S_OK
Операция поиска прошла успешно.
MAPI_E_BUSY
Выполняется другая операция, которая предотвращает запуск операции поиска строк. Либо выполняющиеся операции должны быть разрешены к завершению, либо она должна быть остановлена.
MAPI_E_INVALID_BOOKMARK
Закладка, указанная в параметре bkOrigin , недопустима, так как она была удалена или находится за пределами последней запрошенной строки.
MAPI_W_POSITION_CHANGED
Вызов выполнен успешно, но закладка, указанная в параметре bkOrigin , больше не задается в той же строке, что и при последнем использовании. Если закладка не использовалась, она больше не находится в том же положении, что и при ее создании. При возврате этого предупреждения вызов должен быть обработан как успешный. Чтобы проверить наличие этого предупреждения, используйте макрос HR_FAILED . Дополнительные сведения см. в разделе Использование макросов для обработки ошибок.
Замечания
Метод IMAPITable::SeekRow устанавливает новую позицию BOOKMARK_CURRENT для курсора. Параметр lRowCount указывает количество строк, перемещаемых курсором, и направление перемещения.
Если итоговая позиция находится за последней строкой таблицы, курсор размещается после последней строки. Если результирующая позиция находится перед первой строкой таблицы, курсор размещается в начале первой строки.
Примечания для исполнителей
Если строка, на которую указывает bkOrigin , больше не существует в таблице и вы не можете установить новую позицию для закладки, верните MAPI_E_INVALID_BOOKMARK. Если строка, указываемая на by_bkOrigin_no больше, существует и вы можете установить новую позицию для закладки, верните MAPI_W_POSITION_CHANGED.
Закладка, указывающая на строку, свернутую из табличного представления, по-прежнему можно использовать. Если вызывающий объект пытается переместить курсор в такую закладку, переместите курсор в следующую видимую строку и верните MAPI_W_POSITION_CHANGED.
Вы можете перемещать закладки для позиций, свернутых из представления, либо во время использования, либо во время сворачивания строки. Если закладка перемещается во время сворачивания строки, оставьте в закладке немного, который указывает, была ли закладка перемещена с момента последнего использования или, если она никогда не использовалась, с момента ее создания.
Примечания для вызывающих методов
Чтобы указать движение назад для SeekRow, передайте отрицательное значение в lRowCount. Чтобы выполнить поиск в начале таблицы, передайте ноль в lRowCount , а значение BOOKMARK_BEGINNING в bkOrigin.
Если в таблице много строк, операция SeekRow может выполняться медленно. Производительность также может быть затронута, если требуется возвращать количество строк в содержимом параметра lplRowsSought .
SeekRow возвращает количество фактических строк, по которым выполнен поиск(положительных или отрицательных) в переменной, на которую указывает lRowCount. В обычной операции он должен возвращать то же значение для lplRowsSought , что и для lRowCount, если поиск не достиг начала или конца таблицы.
Не устанавливайте для параметра lRowCount число больше 50. Для поиска большего количества строк используйте метод IMAPITable::SeekRowApprox .
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| MAPIProcessor.cpp |
CMAPIProcessor::P rocessMailboxTable |
MFCMAPI использует метод IMAPITable::SeekRow для поиска начала таблицы перед обработкой. |