IMAPITable::SortTable

The IMAPITable::SortTable method orders the rows of the table based on sort criteria.

Quick Info

HRESULT SortTable(
  LPSSortOrderSet lpSortCriteria,   
  ULONG ulFlags                     
);

Parameters

lpSortCriteria

[in] Pointer to an SSortOrderSet structure containing the sort criteria to apply. Passing an SSortOrderSet structure containing zero columns indicates that the table does not need to be sorted in any particular order.

ulFlags

[in] Bitmask of flags that controls the timing of the IMAPITable::SortTable operation. The following flags can be set:

TBL_ASYNC: Starts the operation asynchronously and returns before the operation completes.
TBL_BATCH: Defers the completion of the sort until the data in the table is required.

Return Values

S_OK

The sort operation was successful.

MAPI_E_BUSY

Another operation is in progress that prevents the sort operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

MAPI_E_NO_SUPPORT

The table does not support the type of sorting requested.

MAPI_E_TOO_COMPLEX

The table cannot perform the operation because the particular sort criteria pointed to by the lpSortCriteria parameter is too complicated. SortTable can return MAPI_E_TOO_COMPLEX when:

A sort operation is requested for a property column that the implementation cannot sort.
The implementation does not support the sort order requested in the ulOrder member of the SSortOrderSet structure.
The number of columns to be sorted, as specified in the cSorts member in SSortOrderSet, is larger than the implementation can handle.
A sort operation is requested, as indicated by a property tag in SSortOrderSet, based on a property that is not in the available or active set and the implementation does not support sorting on properties not in the available set.
One property is specified multiple times in a sort order set, as indicated by multiple instances of the same property tag, and the implementation cannot perform such a sort operation.
A sort operation based on multivalued property columns is requested using MVI_FLAG and the implementation does not support sorting on multivalued properties.
A property tag for a property in SSortOrderSet specifies a property or type that the implementation does not support.
A sort operation other than one that proceeds through the table from the PR_RENDERING_POSITION property forward is specified only for an attachment table that supports this type of sorting.

Remarks

The IMAPITable::SortTable method orders the rows in a table view. Whereas some tables support both standard and categorized sorting on a variety of sort key columns, other tables are more limited in their support. Address book providers commonly do not support table sorting. Message store providers commonly support sorting to the extent that they retain the sort order of folders that results when a full table — that is, a table with no 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 SortOrder call. Some tables require that sort keys be built only with columns in the table's current column set.

A table will return either MAPI_E_NO_SUPPORT or MAPI_E_TOO_COMPLEX from SortTable when it cannot complete a sort operation for whatever reason.

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, indicating the current cursor position, should be set to the beginning of the table.

If sorting on a column containing a multivalued property without the MVI_FLAG flag set, the column's values are treated as a totally 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 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.

Notes to Callers

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 proceed 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 calling SortTable to perform the sort.

Whenever SortTable fails, the sort order that was in effect before the failure is still in effect.