IMAPITable::SortTable

Article
08/28/2006

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

Note This method is supported for contents tables only.

Syntax

HRESULT SortTable (
  LPSSortOrderSet lpSortCriteria,
  ULONG ulFlags
);

Parameters

lpSortCriteria
[in] Reference to an SSortOrderSet structure containing the sort criteria to apply; cannot be NULL. See Remarks for information about the restrictions on the members of this parameter.
ulFlags
[in] Not used; must be zero.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
Indicates success.
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.

Remarks

The SSortOrderSet structure that is referenced by the lpSortCriteria parameter has the following restrictions:

The cSorts member must be either 0 (no sort performed) or 1 (sort on the criterion specified by the aSort[0] member).
The cCategories member must be 0.
The cExpanded member must be 0.
The aSort[0].ulOrder member cannot be TABLE_SORT_COMBINE.
The aSort[0].ulPropTag member must be one of the following:
- PR_MESSAGE_DELIVERY_TIME (Sort by time received.)
- PR_SENDER_NAME_W (Sort by sender.)
- PR_SUBJECT_W (Sort by subject.)
- PR_CONTENT_LENGTH (Sort by size.)

When there are zero columns in the SSortOrderSet structure pointed to by the lpSortCriteria parameter, the table returns the current column set.

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.

For best performance, call IMAPITable::SetColumns to customize the table's column set and IMAPITable::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 remains in effect.

Requirements

Pocket PC: Pocket PC 2002 and later
Smartphone: Smartphone 2002 and later
OS Versions: Windows CE 3.0 and later
Header: mapidefs.h
Library: cemapi.lib

Share via