EDataBook.DataBookCursorStepFunc
Description: Reference for EDataBook.DataBookCursorStepFunc

### 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.