Virtual Method

EDataBookDataBookCursorstep

since: 3.12

Declaration [src]

gint
step (
  EDataBookCursor* cursor,
  const gchar* revision_guard,
  EBookCursorStepFlags flags,
  EBookCursorOrigin origin,
  gint count,
  GSList** results,
  GCancellable* cancellable,
  GError** error
)

Description [src]

Steps cursor 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 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.

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 user facing reference documentation.

Available since: 3.12

Parameters

revision_guard

Type: const gchar*

The expected current addressbook revision, or NULL.

The argument can be NULL.
The data is owned by the caller of the method.
The value is a NUL terminated UTF-8 string.
flags

Type: EBookCursorStepFlags

The EBookCursorStepFlags for this step.

origin

Type: EBookCursorOrigin

The EBookCursorOrigin from whence to step.

count

Type: gint

A positive or negative amount of contacts to try and fetch.

results

Type: A list of utf8

A return location to store the results, or NULL if E_BOOK_CURSOR_STEP_FETCH is not specified in flags.

The argument will be set by the function.
The argument can be set to NULL by the virtual function.
The caller of the method takes ownership of the returned data, and is responsible for freeing it.
Each element is a NUL terminated UTF-8 string.
cancellable

Type: GCancellable

A GCancellable.

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 a NULL GError*.
The argument will be left initialized to NULL by the virtual function 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.

Return value

Type: gint

The number of contacts traversed if successful, otherwise -1 is returned and error is set.