Method
EBookBookClientCursorstep_sync
since: 3.12
Declaration [src]
gint
e_book_client_cursor_step_sync (
EBookClientCursor* cursor,
EBookCursorStepFlags flags,
EBookCursorOrigin origin,
gint count,
GSList** out_contacts,
GCancellable* cancellable,
GError** error
)
Description [src]
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 cursor 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 GSList pointer should be provided for the results parameter.
If E_BOOK_CURSOR_STEP_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 EBookClientCursor: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 E_CLIENT_ERROR_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 E_CLIENT_ERROR_OUT_OF_SYNC error is guaranteed
to be followed by an EBookClientCursor::refresh signal at which point any content
should be reloaded.
Available since: 3.12
Parameters
flags-
Type:
EBookCursorStepFlagsThe
EBookCursorStepFlagsfor this step. origin-
Type:
EBookCursorOriginThe
EBookCursorOriginfrom whence to step. count-
Type:
gintA positive or negative amount of contacts to try and fetch.
out_contacts-
Type: A list of
EContact*Return location for a
GSListofEContact.The argument will be set by the function. The argument can be NULL.The caller of the method takes ownership of the returned data, and is responsible for freeing it. cancellable-
Type:
GCancellableA
GCancellableto optionally cancel this operation while in progress.The argument can be NULL.The data is owned by the caller of the method. error-
Type:
GError **The return location for a recoverable error.
The argument can be NULL.If the return location is not NULL, then you must initialize it to aNULLGError*.The argument will be left initialized to NULLby the method if there are no errors.In case of error, the argument will be set to a newly allocated GError; the caller will take ownership of the data, and be responsible for freeing it.