Setting a Table Position with a Bookmark

A bookmark is a resource that indicates a particular location in a table. Setting a bookmark makes it possible to return to a position at a later time, a feature that can significantly improve the performance of table operations. MAPI defines three standard bookmarks:

Table implementers are required to support these standard bookmarks and can also support others. However, because bookmarks are resources and resources are limited, bookmark users should free them as soon as possible.

To set a bookmark at the current table position

• Call IMAPITable::CreateBookmark.

  Occasionally there will be insufficient memory available to allocate the new bookmark, causing CreateBookmark to return the MAPI_E_UNABLE_TO_COMPLETE error value.

To free a bookmark

• Call IMAPITable::FreeBookmark.

To move the cursor to a bookmarked position

• Call IMAPITable::SeekRow.

  SeekRow establishes a new value for the BOOKMARK_CURRENT position. SeekRow can be used, for example, to position a table ten rows from the current position or to start over at the beginning. Clients or service providers can seek to the current, beginning, or end of a table, or any other position that is associated with a predefined bookmark. They can move in either a forward or backward direction and limit the operation to a specified number of rows. As a rule, callers should seek through no more than 50 rows with SeekRow; IMAPITable::SeekRowApprox should be used with larger numbers of rows.