EBook.BookClientCursor.step_sync

### Method

# EBook BookClientCursorstep_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: `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.

`out_contacts`

  Type: A list of `EContact*`

  Return location for a `GSList` of `EContact`.

  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: `GCancellable`

  A `GCancellable` to 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 a `NULL` `GError*`.
  The argument will be left initialized to `NULL` by 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.

#### Return value

Type: `gint`

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