Published: July 16, 2012
The IMAPITable::SortTable method orders the rows of the table, depending on sort criteria.
The IMAPITable::SortTable method orders the rows in a table view. Whereas some tables support both standard and categorized sorting on various sort key columns, other tables are more limited in their support. Address book providers ordinarily do not support table sorting. Message store providers usually support sorting to the extent that they keep the sort order of folders that results when a full table (a table without restrictions) is sorted.
Some tables allow sorting to be done on any table column. Other tables do not; columns not included in the table view are unaffected by a SortTable call. Some tables require that sort keys be built only with columns in the table's current column set.
A table can return either MAPI_E_NO_SUPPORT or MAPI_E_TOO_COMPLEX from SortTable when it cannot complete a sort operation. Moreover, store providers are not guaranteed to honor the sort order set specified for hierarchy tables.
When there are zero columns in the SSortOrderSet structure pointed to by the lpSortCriteria parameter, the table returns the current column set. The current sort order can be retrieved by calling the table's IMAPITable::QuerySortOrder method.
All bookmarks for a table are invalidated and should be deleted when a call to SortTable is made, and the BOOKMARK_CURRENT bookmark that indicates the current cursor position, should be set to the beginning of the table.
If you are sorting on a column that contains a multivalued property without the MVI_FLAG flag set, the column's values are treated as a completely ordered tuple. A comparison of two multivalued columns compares the column elements in order, reporting the relation of the columns at the first inequality, and returns equality only if the columns being compared contain the same values in the same order. If one column has fewer values than the other, the reported relation is that of a null value to the other value.
SortTable operates synchronously unless you set one of the flags. If you set the TBL_BATCH flag, SortTable postpones the sort operation unless you request the data. If the TBL_ASYNC flag is set, SortTable operates asynchronously, potentially returning before the completion of the operation.
Call the IMAPITable::Abort method to stop an asynchronous operation in progress if your sort must be done immediately. If SortTable cannot continue because one or more asynchronous operations on the table are in progress, it returns MAPI_E_BUSY.
For best performance, call SetColumns to customize the table's column set and Restrict to limit the number of rows in the table before you call SortTable to perform the sort.
Whenever SortTable fails, the sort order that was in effect before the failure is still in effect.