IMAPITable::CreateBookmark

The IMAPITable::CreateBookmark method marks the table's current position.

Quick Info

HRESULT CreateBookmark(
  BOOKMARK FAR * lpbkPosition  
);

Parameters

lpbkPosition: [out] Pointer to the returned 32-bit bookmark value. This bookmark can later be passed in a call to the IMAPITable::SeekRow method.

Return Values

S_OK: The call succeeded and has returned the expected value or values.
MAPI_E_UNABLE_TO_COMPLETE: The requested operation could not be completed.

Remarks

The IMAPITable::CreateBookmark method marks a table position by creating a value called a bookmark. A bookmark can be used to return to the position identified by the bookmark. The bookmarked position is associated with the object at that row in the table.

Bookmarks are not supported on attachment tables, and attachment table implementations of CreateBookmark return MAPI_E_NO_SUPPORT.

Notes to Implementers

Because of the memory expense of maintaining cursor positions with bookmarks, limit the number of bookmarks that you can create. When you reach that number, return MAPI_E_UNABLE_TO_COMPLETE from all subsequent calls to CreateBookmark.

Sometimes a bookmark points to a row that is no longer in the table view. If a caller uses such a bookmark, move the cursor to the next visible row and stop there.

When the caller attempts to use a bookmark that is pointing to a nonvisible row because it has been collapsed, return MAPI_W_POSITION_CHANGED after moving the bookmark. You can reposition the bookmark to the next visible row either at this time or when the collapsing occurs in the SetCollapseState method. If you move the bookmark at the time the row is collapsed, you must retain a bit in the bookmark that indicates exactly when the bookmark was moved: since its last use or — if it has never been used — since its creation.

Notes to Callers

CreateBookmark allocates memory for the bookmark it creates. Release the resources for the bookmark by calling the IMAPITable::FreeBookmark method.