IMAPITable::SeekRow

The IMAPITable::SeekRow method moves the cursor to a specific position in the table.

Quick Info

HRESULT SeekRow(
  BOOKMARK bkOrigin,        
  LONG lRowCount,           
  LONG FAR * lplRowsSought  
);

Parameters

bkOrigin

[in] Bookmark identifying the starting position for the seek operation. A bookmark can be created using the IMAPITable::CreateBookmark method, or one of the following predefined values can be passed:

BOOKMARK_BEGINNING: Starts the seek operation from the beginning of the table.
BOOKMARK_CURRENT: Starts the seek operation from the row in the table where the cursor is located.
BOOKMARK_END: Starts the seek operation from the end of the table.

lRowCount

[in] Signed count of the number of rows to move, starting from the bookmark identified by the bkOrigin parameter.

lplRowsSought

[in-out] If lplRowsSought is a valid pointer on input, on output it points to the number of rows that were processed in the seek operation. If lplRowsSought is NULL on input — indicating that the caller is not interested in the number of rows processed — nothing is returned on output.

Return Values

S_OK: The seek operation was successful.
MAPI_E_BUSY: Another operation is in progress that prevents the row seeking operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.
MAPI_E_INVALID_BOOKMARK: The bookmark specified in the bkOrigin parameter is invalid because it has been removed or because it is beyond the last row requested.
MAPI_W_POSITION_CHANGED: The call succeeded, but the bookmark specified in the bkOrigin parameter is no longer set at the same row as when it was last used. If the bookmark has not been used, it is no longer in the same position as when it was created. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

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 placed at the beginning of the first row.

Notes to Implementers

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 the row is collapsed. If a bookmark is moved at the time 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.

Notes to Callers

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 large numbers of rows in the table, the SeekRow operation can be slow. Performance can also be impacted 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 lplRowsSought. In normal 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.