IMAPITable::QueryRows
Область применения: Outlook 2013 | Outlook 2016
Возвращает одну или несколько строк из таблицы, начиная с текущей позиции курсора.
HRESULT QueryRows(
LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
);
Параметры
lRowCount
[в] Максимальное количество возвращаемых строк.
ulFlags
[в] Битовая маска флагов, управляющих способом возврата строк. Можно задать следующий флаг:
TBL_NOADVANCE
Предотвращает перемещение курсора в результате извлечения строки. Если флаг TBL_NOADVANCE установлен, курсор указывает на первую возвращенную строку. Если флаг TBL_NOADVANCE не задан, курсор указывает на строку после последней возвращенной строки.
lppRows
[out] Указатель на указатель на структуру SRowSet , содержащую строки таблицы.
Возвращаемое значение
S_OK
Строки были успешно возвращены.
MAPI_E_BUSY
Выполняется другая операция, которая предотвращает запуск операции извлечения строк. Либо выполняющиеся операции должны быть разрешены к завершению, либо она должна быть остановлена.
MAPI_E_INVALID_PARAMETER
Параметр IRowCount имеет значение ноль.
Замечания
Метод IMAPITable::QueryRows получает одну или несколько строк данных из таблицы. Значение параметра IRowCount влияет на начальную точку получения. Если значение IRowCount положительное, строки считываются в направлении вперед, начиная с текущей позиции. Если значение IRowCount отрицательное, QueryRows сбрасывает начальную точку, перемещая указанное число строк назад. После сброса курсора строки считываются в порядке пересылки.
Элемент cRows в структуре SRowSet , на который указывает параметр lppRows , указывает количество возвращаемых строк. Если возвращается ноль строк:
Курсор уже был расположен в начале таблицы, а значение IRowCount отрицательное. -Или-
Курсор уже размещен в конце таблицы, и значение IRowCount является положительным.
Количество столбцов и их упорядочение одинаковы для каждой строки. Если свойство не существует для строки или возникает ошибка при чтении свойства, структура SPropValue для свойства в строке содержит следующие значения:
PT_ERROR для типа свойства в элементе ulPropTag .
MAPI_E_NOT_FOUND для элемента Value .
Память, используемая для структур SPropValue в наборе строк, на который указывает параметр lppRows, должна выделяться отдельно и освобождаться для каждой строки. Используйте MAPIFreeBuffer , чтобы освободить структуры значений свойств и освободить набор строк. Однако при вызове QueryRows возвращается ноль, указывающий начало или конец таблицы, необходимо освободить только саму структуру SRowSet . Дополнительные сведения о выделении и освобождении памяти в структуре SRowSet см. в разделе Управление памятью для структур ADRLIST и SRowSet.
Возвращаемые строки и порядок их возврата зависят от того, были ли выполнены успешные вызовы к IMAPITable::Restrict и IMAPITable::SortTable. Ограничьте фильтрацию строк из представления, в результате чего QueryRows возвращает только те строки, которые соответствуют условиям, указанным в ограничении. SortTable устанавливает стандартный или классифицированный порядок сортировки, влияя на последовательность строк, возвращаемых QueryRows. Возвращаемые строки находятся в порядке, указанном в структуре SSortOrderSet , переданной в SortTable.
Столбцы, возвращаемые для каждой строки, и порядок их возврата зависят от того, был ли выполнен успешный вызов IMAPITable::SetColumns. SetColumns устанавливает набор столбцов, указывающий свойства, которые должны быть включены в столбцы таблицы, и порядок их включения. Если был выполнен вызов SetColumns , конкретные столбцы в каждой строке и порядок этих столбцов соответствуют набору столбцов, указанному в вызове. Если вызов SetColumns не выполнен, таблица возвращает набор столбцов по умолчанию.
Если ни один из этих вызовов не выполнен, QueryRows возвращает все строки в таблице. Каждая строка содержит столбец по умолчанию, заданный по умолчанию.
Если набор столбцов, установленный в вызове IMAPITable::SetColumns , содержит столбцы, для PR_NULL, массив SPropValue в наборе строк, возвращаемом в lppRows , будет содержать пустые слоты.
Примечания для исполнителей
Вы можете разрешить вызывающей стороны запросить включение неподдерживаемого столбца в набор столбцов. В этом случае поместите PT_ERROR в часть типа свойства тега свойства и MAPI_E_NOT_FOUND в значение свойства неподдерживаемого столбца.
Обрабатывать число строк как запрос, а не как требование. Вы можете вернуть в любом месте от нуля строк, если нет строк в направлении запроса, до запрошенного числа.
Возвращает только те строки, которые пользователь будет видеть при запросе строк из представления таблицы с классификацией, что позволяет вызывающему объекту делать допустимые предположения о область данных и избегать дополнительной работы.
Примечания для вызывающих методов
Обычно в конечном итоге у вас будет столько строк, сколько указано в параметре lRowCount . Однако если возникают проблемы с ограничениями памяти или реализации или когда операция достигает начала или конца таблицы преждевременно, QueryRows вернет меньше строк, чем запрошено.
Если QueryRows возвращает MAPI_E_BUSY, вызовите метод IMAPITable::WaitForCompletion и повторите вызов QueryRows после завершения асинхронной операции.
При вызове QueryRows имейте в виду, что время асинхронных уведомлений может привести к тому, что набор строк, возвращаемых из QueryRows , не будет точно представлять базовые данные. Например, вызов QueryRows к таблице содержимого папки после удаления сообщения, но до получения соответствующего уведомления приведет к возврату удаленной строки в наборе строк. Всегда подождите, пока не появится уведомление, прежде чем обновлять представление данных пользователя.
Дополнительные сведения о получении строк из таблиц см. в разделе Извлечение данных из строк таблицы.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
MFCMAPI использует метод IMAPITable::QueryRows для получения строк в таблице для загрузки в представление. |