Function

EDataBookDataBookCursorStepFunc

since: 3.12

Declaration

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

Description [src]

Method type for EDataBookCursorClass.step()

As all cursor methods may be called either by the addressbook service or directly by a client in Direct Read Access mode, it is important that the operation be an atomic transaction with the underlying database.

The revision_guard, if specified, will be set to the CLIENT_BACKEND_PROPERTY_REVISION value at the time which the given client issued the call to move the cursor. If the revision_guard provided by the client does not match the stored addressbook revision, then an E_CLIENT_ERROR_OUT_OF_SYNC error should be set to indicate that the revision was out of sync while attempting to move the cursor.

If the addressbook backend supports direct read access, then the revision comparison and reading of the data store must be coupled into a single atomic operation (the data read back from the store must be the correct data for the given addressbook revision).

See e_data_book_cursor_step() for more details on the expected behaviour of this method.

Available since: 3.12

Parameters

cursor

Type: EDataBookCursor

An EDataBookCursor.

The data is owned by the caller of the function.
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 function.
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 function.
The caller of the function 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 function.
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 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.