IMAPITable::SetColumns
Область применения: Outlook 2013 | Outlook 2016
Определяет конкретные свойства и порядок свойств, которые будут отображаться в виде столбцов в таблице.
HRESULT SetColumns(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags
);
Параметры
lpPropTagArray
[в] Указатель на массив тегов свойств, определяющих свойства, которые должны быть включены в таблицу в виде столбцов. Для части типа свойства каждого тега можно задать допустимый тип или PR_NULL , чтобы зарезервировать место для последующих добавлений. Параметр lpPropTagArray не может иметь значение NULL; каждая таблица должна содержать по крайней мере один столбец.
ulFlags
[в] Битовая маска флагов, управляющая возвратом асинхронного вызова SetColumns, например при использовании SetColumns в уведомлении. Можно задать следующие флаги:
TBL_ASYNC
Запрашивает выполнение операции настройки столбца асинхронно, что приводит к потенциальному возврату SetColumns до полного завершения операции.
TBL_BATCH
Позволяет таблице отложить операцию настройки столбца до тех пор, пока данные не потребуются.
Возвращаемое значение
S_OK
Операция настройки столбца прошла успешно.
MAPI_E_BUSY
Выполняется другая операция, которая предотвращает запуск операции настройки столбца. Либо выполняющиеся операции должны быть разрешены к завершению, либо она должна быть остановлена.
Замечания
Набор столбцов таблицы — это группа свойств, составляющих столбцы для строк в таблице. Для каждого типа таблицы задан столбец по умолчанию. Набор столбцов по умолчанию состоит из свойств, которые автоматически включает средство реализации таблицы. Пользователи таблиц могут изменить этот набор по умолчанию, вызвав метод IMAPITable::SetColumns . Они могут запросить добавление других столбцов в набор по умолчанию, если реализующий таблицу поддерживает их удаление столбцов или изменение порядка столбцов. SetColumns указывает столбцы, возвращаемые каждой строкой, и порядок этих столбцов в строке.
Успешное выполнение операции SetColumns становится очевидным только после последующего вызова для получения данных таблицы. Именно тогда будут сообщаться о всех ошибках.
Примечания для исполнителей
Некоторые поставщики разрешают вызов SetColumns , чтобы упорядочить только столбцы таблицы, которые являются частью доступных столбцов для табличного представления. Другие поставщики разрешают вызов SetColumns для упорядочения всех столбцов таблицы, включая те, которые содержат свойства, отсутствующие в исходном наборе столбцов.
Если TBL_BATCH задано для асинхронных операций, поставщики должны возвращать тип свойства PT_ERROR и значение свойства NULL для столбцов, которые не поддерживаются.
Не нужно отвечать на флаг TBL_ASYNC, требуя, чтобы операция была асинхронной. Если вы не поддерживаете асинхронное определение набора столбцов, выполните операцию синхронно. Если вы можете поддерживать флаг TBL_ASYNC и еще выполняется другая асинхронная операция, верните MAPI_E_BUSY. В противном случае верните S_OK независимо от того, поддерживаете ли вы все свойства, включенные в массив тегов свойств. Ошибки, возникающие из-за неподдерживаемых свойств, должны возвращаться из методов IMAPITable , которые извлекают данные, например QueryRows.
Не создавайте уведомления для строк таблицы, скрытых от просмотра вызовами Restrict.
При отправке табличных уведомлений порядок свойств в элементе строкиструктуры TABLE_NOTIFICATION и порядок, заданный последним вызовом SetColumns , должен совпадать с временем отправки запроса уведомления.
Другой флаг, TBL_BATCH, позволяет вызывающим пользователям указать, что реализующий таблицу может отложить оценку результатов операции на более позднее время. По возможности вызывающие пользователи должны установить этот флаг, так как пакетная операция повышает производительность.
Вызывающим абонентам часто удобно зарезервировать некоторые столбцы в полученном наборе строк для добавления значений позже. Вызывающие объекты делают это, помещая PR_NULL (PidTagNull) в нужные позиции в массиве тегов свойств, переданном в SetColumns; Затем таблица будет передавать обратно PR_NULL в этих позициях во всех строках, полученных с помощью QueryRows.
Примечания для вызывающих методов
При создании массива тегов свойств для параметра lpPropTagArray упорядочение тегов в том порядке, в который должны отображаться столбцы в табличном представлении.
Вы можете указать многозначные свойства, которые будут включены в набор столбцов, применив к тегу свойства флаг многозначного экземпляра или MVI_FLAG константы. Установите этот флаг, передав тег свойства для однозначной версии свойства в качестве параметра в макрос MVI_PROP следующим образом:
MVI_PROP(ulPropTag)
Макрос MVI_PROP задаст MVI_FLAG для свойства, превратив тег в многозначный тег. Если вы ошибочно попытаетесь вызвать MVI_PROP для свойства с одним значением, MAPI проигнорирует вызов и оставит тег свойства без изменений.
Чтобы зарезервировать место в наборе столбцов, в массив тегов свойств можно включить теги свойств, для которых задано значение PR_NULL . Резервирование пространства позволяет добавлять в набор столбцов без выделения нового массива тегов свойств.
Если вызов SetColumns приводит к изменению порядка столбцов таблицы, а один или несколько из этих столбцов представляют многозначное свойство, количество строк в таблице может увеличиться. В этом случае все закладки для таблицы удаляются. Дополнительные сведения о том, как многозначные столбцы влияют на таблицы, см. в разделе Работа с многозначными столбцами.
Настройка столбцов по умолчанию является синхронной операцией. Однако можно разрешить таблице отложить операцию до тех пор, пока данные не потребуются, установив флаг TBL_BATCH. Установка этого флага может повысить производительность. Другой флаг, TBL_ASYNC, делает операцию асинхронной, позволяя SetColumns возвращать данные до завершения операции. Чтобы определить, когда происходит завершение, вызовите IMAPITable::GetStatus.
Если вызов SetColumns возвращает MAPI_E_BUSY, указывающий, что другая операция препятствует запуску операции, можно вызвать IMAPITable::Abort , чтобы остановить выполнение операции.
Вы также можете вызвать HrAddColumnsEx , чтобы изменить набор столбцов. Разница между HrAddColumnsEx и IMAPITable::SetColumns заключается в том, что HrAddColumnsEx менее гибкий; он может добавлять только столбцы. Дополнительные столбцы размещаются в начале набора столбцов; все существующие столбцы отображаются после этих столбцов.
Справочные материалы по MFCMAPI
Пример кода MFCMAPI указан в приведенной ниже таблице.
| Файл | Функция | Comment |
|---|---|---|
| ContentsTableListCtrl.cpp |
CContentsTableListCtrl::D oSetColumns |
MFCMAPI использует метод IMAPITable::SetColumns для задания нужных столбцов для таблицы. |