IMAPITable::SeekRow
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Moves the cursor to a specific position in the table.
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 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 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. 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 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.
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. |