Steps this through its sorted query by a maximum of count contacts starting from
origin.
If count is negative, then the cursor will move through the list in reverse.
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 e_client_error_query_refused error.
If e_book_cursor_step_fetch is specified in flags, a pointer to a
null SList pointer should be provided for the
results parameter.
The result list will be stored to results and should be freed with g_slist_free and all elements freed with
g_free.
If a revision_guard is specified, the cursor implementation will issue an
e_client_error_out_of_sync error if the revision_guard does not match the current addressbook revision.
An explanation of how stepping is expected to behave can be found in the <link linkend="cursor-iteration">user facing reference documentation</link>.
| this | |
| revision_guard |
The expected current addressbook revision, or null |
| 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 |
| results |
A return location to store the results, or null if
e_book_cursor_step_fetch is not specified in |
| cancellable |
|
The number of contacts traversed if successful, otherwise -1 is returned and throws is set. |