IMAPITable::SortTable

  • Article

4/8/2010

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 Value

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

Header mapidefs.h
Library cemapi.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Pocket PC 2002 and later, Smartphone 2002 and later

See Also

Reference

IMAPITable
IMAPITable::SetColumns
SSortOrderSet

Other Resources

Messaging