Share via

IMAPITable::SeekRow

  • Article

Applies to: Office 2010 | Outlook 2010 | Visual Studio

In this article
Notes to Implementers
Notes to Callers
MFCMAPI Reference

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.

See Also

Reference

IMAPITable::CreateBookmark

IMAPITable::FindRow

IMAPITable::QueryRows

IMAPITable::SeekRowApprox

IMAPITable : IUnknown

Concepts

MFCMAPI as a Code Sample