Published: July 16, 2012
Moves the cursor to a specific position in the table.
The IMAPITable::SeekRow method establishes a new BOOKMARK_CURRENT position for the cursor. The lRowCount parameter indicates the number of rows that the cursor moves and the direction of movement.
If the resulting position is beyond the last row of the table, the cursor is positioned after the last row. If the resulting position is before the first row of the table, the cursor is positioned at the beginning of the first row.
If the row pointed to by bkOrigin no longer exists in the table and you cannot establish a new position for the bookmark, return MAPI_E_INVALID_BOOKMARK. If the row pointed to by bkOrigin no longer exists and you can establish a new position for the bookmark, return MAPI_W_POSITION_CHANGED.
A bookmark pointing to a row that is collapsed out of the table view can still be used. If the caller attempts to move the cursor to such a bookmark, move the cursor to the next visible row and return MAPI_W_POSITION_CHANGED.
You can move bookmarks for positions collapsed out of view, either at the time of use or at the time that the row is collapsed. If a bookmark is moved at the time that the row is collapsed, keep a bit in the bookmark that indicates whether the bookmark has moved since its last use or, if it has never been used, since its creation.
To indicate a backward move for SeekRow, pass a negative value in lRowCount. To search to the beginning of the table, pass zero in lRowCount and the value BOOKMARK_BEGINNING in bkOrigin.
If there are lots of rows in the table, the SeekRow operation can be slow. Performance can also be affected if you require a row count to be returned in the contents of the lplRowsSought parameter.
SeekRow returns the number of rows actually searched through, positive or negative, in the variable pointed to by lRowCount. In ordinary operation, it should return the same value for lplRowsSought as passed in for lRowCount, unless the search reached the beginning or end of the table.
Do not set lRowCount to a number greater than 50. To seek through a larger number of rows, use the IMAPITable::SeekRowApprox method.