step_sync
Description:
Steps the cursor through the results by a maximum of count and fetch the results traversed.
If count is negative, then the cursor will move backwards.
If this reaches the beginning or end of the query results, then the returned list might not contain the amount of desired contacts, or might return no results if the cursor currently points to the last contact. Reaching the end of the list is not considered an error condition. Attempts to step beyond the end of the list after having reached the end of the list will however trigger an QUERY_REFUSED error.
If FETCH is specified in flags, a pointer
to a null SList pointer should be provided for the results
parameter.
If MOVE is specified in flags, then the
cursor's state will be modified and the position property will be updated as a result.
If this method is called from the same thread context in which the cursor was created, then the updates to the position property are guaranteed to be delivered synchronously upon successful completion of moving the cursor. Otherwise, notifications will be delivered asynchronously in the cursor's original thread context.
If this method completes with an OUT_OF_SYNC error, it is an indication that the addressbook has been modified and it would be unsafe to move the cursor at this time. Any OUT_OF_SYNC error is guaranteed to be followed by an refresh signal at which point any content should be reloaded.
Parameters:
| this | |
| flags |
The BookCursorStepFlags for this step |
| origin |
The BookCursorOrigin from whence to step |
| count |
a positive or negative amount of contacts to try and fetch |
| out_contacts | |
| cancellable |
a Cancellable to optionally cancel this operation while in progress |
Returns:
|
The number of contacts traversed if successful, otherwise -1 is returned and |