IMAPITable::SeekRow

Article
06/01/2022

Applies to: Outlook 2013 | Outlook 2016

Moves the cursor to a specific position in the table.

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

Parameters

bkOrigin

[in] The 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] The signed count of the number of rows to move, starting from the bookmark identified by the bkOrigin parameter.

lplRowsSought

[out] If lRowCount is a valid pointer on input, lplRowsSought points to the number of rows that were processed in the seek operation, the sign of which indicates the direction of search, forward or backward. If lRowCount is negative, then lplRowsSought is negative.

Return value

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 was 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 it was when it was last used. If the bookmark has not been used, it is no longer in the same position as it was 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. For more information, 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 positioned 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 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.

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 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.

MFCMAPI reference

For MFCMAPI sample code, see the following table.

File	Function	Comment
MAPIProcessor.cpp	CMAPIProcessor::ProcessMailboxTable	MFCMAPI uses the IMAPITable::SeekRow method to locate the beginning of the table before processing.