IMAPITable::SortTable

  • 项目

适用于：Outlook 2013 | Outlook 2016

IMAPITable：：SortTable 方法根据排序条件对表的行进行排序。

HRESULT SortTable(
LPSSortOrderSet lpSortCriteria,
ULONG ulFlags
);

参数

lpSortCriteria

[in]指向包含要应用的排序条件的 SSortOrderSet 结构的指针。 传递包含零列的 SSortOrderSet 结构表示不必按任何特定顺序对表进行排序。

ulFlags

[in]控制 IMAPITable：：SortTable 操作计时的标志的位掩码。 可以设置以下标志：

TBL_ASYNC

异步启动操作，并在操作完成之前返回。

TBL_BATCH

延迟排序完成，直到需要表中的数据。

返回值

S_OK

排序操作成功。

MAPI_E_BUSY

另一个操作正在进行中，该操作阻止排序操作启动。 应允许正在进行的操作完成，或者应停止该操作。

MAPI_E_NO_SUPPORT

表不支持所请求的排序类型。

MAPI_E_TOO_COMPLEX

表无法执行操作，因为 lpSortCriteria 参数指向的特定排序条件太复杂。 在以下条件下，SortTable 可以返回MAPI_E_TOO_COMPLEX。

  • 对实现无法排序的属性列请求排序操作。

  • 实现不支持在 SSortOrderSet 结构的 ulOrder 成员中请求的排序顺序。

  • 要排序的列数（如 SSortOrderSet 中的 cSorts 成员中指定的）大于实现可以处理的列数。

  • 根据不在可用或活动集中的属性，请求排序操作，如 SSortOrderSet 中的属性标记所指示的那样，实现不支持对不在可用集中的属性进行排序。

  • 一个属性在排序顺序集中多次指定，由同一属性标记的多个实例指示，并且实现无法执行此类排序操作。

  • 使用 MVI_FLAG 请求基于多值属性列的排序操作，并且该实现不支持对多值属性进行排序。

  • SSortOrderSet 中属性的属性标记指定实现不支持的属性或类型。

  • 除从 PR_RENDERING_POSITION (PidTagRenderingPosition) 属性转发的排序操作之外，仅为支持此类排序的附件表指定排序操作。

备注

IMAPITable：：SortTable 方法对表视图中的行进行排序。 虽然某些表支持对各种排序键列进行标准排序和分类排序，但其他表的支持更加有限。 通讯簿提供程序通常不支持表排序。 邮件存储提供程序通常支持排序，只要它们保留当完整表 (表时所生成文件夹的排序顺序，且不受限制) 排序。

某些表允许对任何表列进行排序。 其他表则不为;未包含在表视图中的列不受 SortTable 调用影响。 某些表要求仅使用表的当前列集中的列生成排序键。

当无法完成排序操作时，表可以从 SortTable 返回MAPI_E_NO_SUPPORT或MAPI_E_TOO_COMPLEX。 此外，不保证存储提供程序遵循为层次结构表指定的排序顺序集。

当 lpSortCriteria 参数指向的 SSortOrderSet 结构中没有列时，表将返回当前列集。 可以通过调用表的 IMAPITable：：QuerySortOrder 方法检索当前的排序顺序。

表的所有书签都将失效，在调用 SortTable 时应将其删除，并且指示当前光标位置的BOOKMARK_CURRENT书签应设置为表的开头。

如果要对包含多值属性的列进行排序，而不设置 MVI_FLAG 标志，则列的值将被视为完全有序的元组。 对两个多值列的比较按顺序比较列元素，报告列在第一个不相等处的关系，并且仅当被比较的列包含相同顺序的相同值时，才返回相等性。 如果一列的值比另一列少，则报告的关系是另一个值为 null 值的关系。

给调用方的说明

除非设置了其中一个标志，否则 SortTable 将同步运行。 如果设置TBL_BATCH标志， 则 SortTable 将推迟排序操作，除非请求数据。 如果设置了TBL_ASYNC标志， SortTable 将异步操作，可能会在操作完成之前返回。

如果必须立即完成排序，请调用 IMAPITable：：Abort 方法来停止正在进行的异步操作。 如果 SortTable 由于表上的一个或多个异步操作正在进行而无法继续，则返回MAPI_E_BUSY。

为获得最佳性能，请在调用 SortTable 执行排序之前，调用 SetColumns 以自定义表的列集，并调用 Restrict 以限制表中的行数。

每当 SortTable 失败时，在失败之前生效的排序顺序仍然有效。

另请参阅