IMAPITable::SetColumns

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

定义要在表中显示为列的属性的特定属性和顺序。

HRESULT SetColumns(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags
);

参数

lpPropTagArray

[in]指向属性标记数组的指针，该数组标识要作为列包含在表中的属性。每个标记的属性类型部分可以设置为有效类型或 PR_NULL ，以便为后续添加保留空间。 lpPropTagArray 参数不能设置为 NULL;每个表必须至少有一列。

ulFlags

[in]控制对 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 的属性标记数组中的所需位置来执行此操作;然后，表将传回使用QueryRows 检索的所有行中的这些位置PR_NULL。

给调用方的说明

为 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 的灵活性较低;它只能添加列。其他列放置在列集的开头;所有现有列都显示在这些列之后。