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:
BOOKMARK_CURRENT | Points to the present row in a table. |
BOOKMARK_BEGINNING | Points to the first row in a table. |
BOOKMARK_END | Points to the last row in a table. |
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.
Occasionally there will be insufficient memory available to allocate the new bookmark, causing CreateBookmark to return the MAPI_E_UNABLE_TO_COMPLETE error value.
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.