ECache: Evolution-Data-Server Reference Manual

## ECache ECache — An SQLite data cache |

## Functions

GQuark | e_cache_error_quark ()
ECacheColumnValues * | e_cache_column_values_new ()
ECacheColumnValues * | e_cache_column_values_copy ()
void | e_cache_column_values_free ()
void | e_cache_column_values_put ()
void | e_cache_column_values_take_value ()
void | e_cache_column_values_take ()
gboolean | e_cache_column_values_contains ()
gboolean | e_cache_column_values_remove ()
void | e_cache_column_values_remove_all ()
const gchar * | e_cache_column_values_lookup ()
guint | e_cache_column_values_get_size ()
void | e_cache_column_values_init_iter ()
ECacheOfflineChange * | e_cache_offline_change_new ()
ECacheOfflineChange * | e_cache_offline_change_copy ()
void | e_cache_offline_change_free ()
ECacheColumnInfo * | e_cache_column_info_new ()
ECacheColumnInfo * | e_cache_column_info_copy ()
void | e_cache_column_info_free ()
gboolean | (*ECacheForeachFunc) ()
gboolean | (*ECacheUpdateFunc) ()
gboolean | (*ECacheSelectFunc) ()
gboolean | e_cache_initialize_sync ()
const gchar * | e_cache_get_filename ()
gint | e_cache_get_version ()
void | e_cache_set_version ()
gchar * | e_cache_dup_revision ()
void | e_cache_set_revision ()
void | e_cache_change_revision ()
void | e_cache_freeze_revision_change ()
void | e_cache_thaw_revision_change ()
gboolean | e_cache_is_revision_change_frozen ()
void | e_cache_erase ()
gboolean | e_cache_contains ()
gchar * | e_cache_get ()
gchar * | e_cache_get_object_include_deleted ()
gboolean | e_cache_put ()
gboolean | e_cache_remove ()
gboolean | e_cache_remove_all ()
guint | e_cache_get_count ()
gboolean | e_cache_get_uids ()
gboolean | e_cache_get_objects ()
gboolean | e_cache_foreach ()
gboolean | e_cache_foreach_update ()
void | e_cache_copy_missing_to_column_values ()
EOfflineState | e_cache_get_offline_state ()
gboolean | e_cache_set_offline_state ()
GSList * | e_cache_get_offline_changes ()
gboolean | e_cache_clear_offline_changes ()
gboolean | e_cache_set_key ()
gchar * | e_cache_dup_key ()
gboolean | e_cache_set_key_int ()
gint | e_cache_get_key_int ()
void | e_cache_lock ()
void | e_cache_unlock ()
gpointer | e_cache_get_sqlitedb ()
gboolean | e_cache_sqlite_exec ()
gboolean | e_cache_sqlite_select ()
gboolean | e_cache_sqlite_maybe_vacuum ()
void | e_cache_sqlite_stmt_append_printf ()
gchar * | e_cache_sqlite_stmt_printf ()
void | e_cache_sqlite_stmt_free ()

## Signals

gboolean | before-put | Run Last
gboolean | before-remove | Run Last
void | revision-changed | Run Last

## Types and Values

#define | E_CACHE_TABLE_OBJECTS
#define | E_CACHE_TABLE_KEYS
#define | E_CACHE_COLUMN_UID
#define | E_CACHE_COLUMN_REVISION
#define | E_CACHE_COLUMN_OBJECT
#define | E_CACHE_COLUMN_STATE
#define | E_CACHE_ERROR
enum | ECacheError
| ECacheOfflineChange
enum | ECacheLockType
enum | ECacheUnlockAction
enum | ECacheDeletedFlag
enum | ECacheOfflineFlag
struct | ECache

## Object Hierarchy

        GBoxed
        ├── ECacheColumnInfo
        ├── ECacheColumnValues
        ╰── ECacheOfflineChange
        GObject
        ╰── ECache
            ├── EBookCache
            ╰── ECalCache

## Includes

    #include <libebackend/libebackend.h>

## Description

The ECache is an abstract class which consists of the common parts which can be used by its descendants. It also allows storing offline state for the stored objects.

The API is thread safe, with special considerations to be made around `e_cache_lock()` and `e_cache_unlock()` for the sake of isolating transactions across threads.

## Functions

### e_cache_error_quark ()

    GQuark
    e_cache_error_quark (void);

### e_cache_column_values_new ()

    ECacheColumnValues *
    e_cache_column_values_new (void);

Creates a new ECacheColumnValues to store values for additional columns. The column names are compared case insensitively.

#### Returns

a new ECacheColumnValues. Free with `e_cache_column_values_free()`, when no longer needed.

[transfer full]

Since: 3.26

### e_cache_column_values_copy ()

    ECacheColumnValues *
    e_cache_column_values_copy (ECacheColumnValues *other_columns);

#### Parameters

other_columns | an ECacheColumnValues. | [nullable]

#### Returns

Copy of the `other_columns` . Free with `e_cache_column_values_free()`, when no longer needed.

[transfer full]

Since: 3.26

### e_cache_column_values_free ()

    void
    e_cache_column_values_free (ECacheColumnValues *other_columns);

Frees previously allocated `other_columns` with `e_cache_column_values_new()` or `e_cache_column_values_copy()`.

#### Parameters

other_columns | an ECacheColumnValues. | [nullable]

Since: 3.26

### e_cache_column_values_put ()

    void
    e_cache_column_values_put (ECacheColumnValues *other_columns,
                               const gchar *name,
                               const gchar *value);

Puts the `value` for column `name` . If contains a value for the same column, then it is replaced. This creates a copy of both `name` and `value` .

#### Parameters

other_columns | an ECacheColumnValues |
name | a column name |
value | a column value. | [nullable]

Since: 3.26

### e_cache_column_values_take_value ()

    void
    e_cache_column_values_take_value (ECacheColumnValues *other_columns,
                                      const gchar *name,
                                      gchar *value);

Puts the `value` for column `name` . If contains a value for the same column, then it is replaced. This creates a copy of the `name` , but takes owner ship of the `value` .

#### Parameters

other_columns | an ECacheColumnValues |
name | a column name |
value | a column value. | [nullable][in][transfer full]

Since: 3.26

### e_cache_column_values_take ()

    void
    e_cache_column_values_take (ECacheColumnValues *other_columns,
                                gchar *name,
                                gchar *value);

Puts the `value` for column `name` . If contains a value for the same column, then it is replaced. This creates takes ownership of both the `name` and the `value` .

#### Parameters

other_columns | an ECacheColumnValues |
name | a column name. | [in][transfer full]
value | a column value. | [nullable][in][transfer full]

Since: 3.26

### e_cache_column_values_contains ()

    gboolean
    e_cache_column_values_contains (ECacheColumnValues *other_columns,
                                    const gchar *name);

#### Parameters

other_columns | an ECacheColumnValues |
name | a column name |

#### Returns

Whether `other_columns` contains column named `name` .

Since: 3.26

### e_cache_column_values_remove ()

    gboolean
    e_cache_column_values_remove (ECacheColumnValues *other_columns,
                                  const gchar *name);

Removes value for the column named `name` from `other_columns` .

#### Parameters

other_columns | an ECacheColumnValues |
name | a column name |

#### Returns

Whether such column existed and had been removed.

Since: 3.26

### e_cache_column_values_remove_all ()

    void
    e_cache_column_values_remove_all (ECacheColumnValues *other_columns);

Removes all values from the `other_columns` , leaving it empty.

#### Parameters

other_columns | an ECacheColumnValues |

Since: 3.26

### e_cache_column_values_lookup ()

    const gchar *
    e_cache_column_values_lookup (ECacheColumnValues *other_columns,
                                  const gchar *name);

Looks up currently stored value for the column named `name` . As the values can be `NULL` one cannot distinguish between a column which doesn't have stored any value and a column which has stored `NULL` value. Use `e_cache_column_values_contains()` to check whether such column exitst in the `other_columns` . The returned pointer is owned by `other_columns` and is valid until the value is overwritten of the `other_columns` freed.

#### Parameters

other_columns | an ECacheColumnValues |
name | a column name |

#### Returns

Stored value for the column named `name` , or `NULL`, if no such column values is stored.

Since: 3.26

### e_cache_column_values_get_size ()

    guint
    e_cache_column_values_get_size (ECacheColumnValues *other_columns);

#### Parameters

other_columns | an ECacheColumnValues |

#### Returns

How many columns are stored in the `other_columns` .

Since: 3.26

### e_cache_column_values_init_iter ()

    void
    e_cache_column_values_init_iter (ECacheColumnValues *other_columns,
                                     GHashTableIter *iter);

Initialized the `iter` , thus the `other_columns` can be traversed with `g_hash_table_iter_next()`. The key is a column name and the value is the corresponding column value.

#### Parameters

other_columns | an ECacheColumnValues |
iter | a GHashTableIter |

Since: 3.26

### e_cache_offline_change_new ()

    ECacheOfflineChange *
    e_cache_offline_change_new (const gchar *uid,
                                const gchar *revision,
                                const gchar *object,
                                EOfflineState state);

Creates a new ECacheOfflineChange with the offline `state` information for the given `uid` .

#### Parameters

uid | a unique object identifier |
revision | a revision of the object. | [nullable]
object | object itself. | [nullable]
state | an EOfflineState |

#### Returns

A new ECacheOfflineChange. Free it with `e_cache_offline_change_free()` when no longer needed.

[transfer full]

Since: 3.26

### e_cache_offline_change_copy ()

    ECacheOfflineChange *
    e_cache_offline_change_copy (const ECacheOfflineChange *change);

#### Parameters

change | a source ECacheOfflineChange to copy, or `NULL`. | [nullable]

#### Returns

Copy of the given `change` . Free it with `e_cache_offline_change_free()` when no longer needed. If the `change` is `NULL`, then returns `NULL` as well.

[transfer full]

Since: 3.26

### e_cache_offline_change_free ()

    void
    e_cache_offline_change_free (gpointer change);

Frees the `change` structure, previously allocated with `e_cache_offline_change_new()` or `e_cache_offline_change_copy()`.

#### Parameters

change | an ECacheOfflineChange. | [nullable]

Since: 3.26

### e_cache_column_info_new ()

    ECacheColumnInfo *
    e_cache_column_info_new (const gchar *name,
                             const gchar *type,
                             const gchar *index_name);

#### Parameters

name | a column name |
type | a column type |
index_name | an index name for this column, or `NULL`. | [nullable]

#### Returns

A new ECacheColumnInfo. Free it with `e_cache_column_info_free()` when no longer needed.

[transfer full]

Since: 3.26

### e_cache_column_info_copy ()

    ECacheColumnInfo *
    e_cache_column_info_copy (const ECacheColumnInfo *info);

#### Parameters

info | a source ECacheColumnInfo to copy, or `NULL`. | [nullable]

#### Returns

Copy of the given `info` . Free it with `e_cache_column_info_free()` when no longer needed. If the `info` is `NULL`, then returns `NULL` as well.

[transfer full]

Since: 3.26

### e_cache_column_info_free ()

    void
    e_cache_column_info_free (gpointer info);

Frees the `info` structure, previously allocated with `e_cache_column_info_new()` or `e_cache_column_info_copy()`.

#### Parameters

info | an ECacheColumnInfo. | [nullable]

Since: 3.26

### ECacheForeachFunc ()

    gboolean
    (*ECacheForeachFunc) (ECache *cache,
                          const gchar *uid,
                          const gchar *revision,
                          const gchar *object,
                          EOfflineState offline_state,
                          gint ncols,
                          const gchar *column_names[],
                          const gchar *column_values[],
                          gpointer user_data);

A callback called for each object row when using `e_cache_foreach()` function.

#### Parameters

cache | an ECache |
uid | a unique object identifier |
revision | the object revision |
object | the object itself |
offline_state | objects offline state, one of EOfflineState |
ncols | count of columns, items in column_names and column_values |
column_names | column names. | [array length=ncols][element-type utf8]
column_values | column values. | [array length=ncols][element-type utf8]
user_data | user data, as used in `e_cache_foreach()` |

#### Returns

`TRUE` to continue, `FALSE` to stop walk through.

Since: 3.26

### ECacheUpdateFunc ()

    gboolean
    (*ECacheUpdateFunc) (ECache *cache,
                         const gchar *uid,
                         const gchar *revision,
                         const gchar *object,
                         EOfflineState offline_state,
                         gint ncols,
                         const gchar *column_names[],
                         const gchar *column_values[],
                         gchar **out_revision,
                         gchar **out_object,
                         EOfflineState *out_offline_state,
                         ECacheColumnValues **out_other_columns,
                         gpointer user_data);

A callback called for each object row when using `e_cache_foreach_update()` function. When all out parameters are left untouched, then the row is not changed.

#### Parameters

cache | an ECache |
uid | a unique object identifier |
revision | the object revision |
object | the object itself |
offline_state | objects offline state, one of EOfflineState |
ncols | count of columns, items in column_names and column_values |
column_names | column names. | [array length=ncols][element-type utf8]
column_values | column values. | [array length=ncols][element-type utf8]
out_revision | the new object revision to set; keep it untouched to not change. | [out]
out_object | the new object to set; keep it untouched to not change. | [out]
out_offline_state | the offline state to set; the default is the same as `offline_state` . | [out]
out_other_columns | an ECacheColumnValues with other columns to set; keep it untouched to not change any. | [out][transfer full]
user_data | user data, as used in `e_cache_foreach_update()` |

#### Returns

`TRUE` to continue, `FALSE` to stop walk through.

Since: 3.26

### ECacheSelectFunc ()

    gboolean
    (*ECacheSelectFunc) (ECache *cache,
                         gint ncols,
                         const gchar *column_names[],
                         const gchar *column_values[],
                         gpointer user_data);

A callback called for each row of a SELECT statement executed with `e_cache_sqlite_select()` function.

#### Parameters

cache | an ECache |
ncols | count of columns, items in column_names and column_values |
column_names | column names. | [array length=ncols][element-type utf8]
column_values | column values. | [array length=ncols][element-type utf8]
user_data | user data, as used in `e_cache_sqlite_select()` |

#### Returns

`TRUE` to continue, `FALSE` to stop walk through.

Since: 3.26

### e_cache_initialize_sync ()

    gboolean
    e_cache_initialize_sync (ECache *cache,
                             const gchar *filename,
                             const GSList *other_columns,
                             GCancellable *cancellable,
                             GError **error);

Initializes the `cache` and opens the `filename` database. This should be called by the descendant.

The `other_columns` are added to the objects table (`E_CACHE_TABLE_OBJECTS` ). Values for these columns are returned by `e_cache_get()` and can be stored with `e_cache_put()`.

#### Parameters

cache | an ECache |
filename | a filename of an SQLite database to use |
other_columns | an optional GSList with additional columns to add to the objects table. | [element-type ECacheColumnInfo][nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_get_filename ()

    const gchar *
    e_cache_get_filename (ECache *cache);

#### Parameters

cache | an ECache |

#### Returns

a filename of the `cache` , with which it had been initialized.

Since: 3.26

### e_cache_get_version ()

    gint
    e_cache_get_version (ECache *cache);

#### Parameters

cache | an ECache |

#### Returns

A cache data version. This is meant to be used by the descendants.

Since: 3.26

### e_cache_set_version ()

    void
    e_cache_set_version (ECache *cache,
                         gint version);

Sets a cache data version. This is meant to be used by the descendants. The `version` should be greater than zero.

#### Parameters

cache | an ECache |
version | a cache data version to set |

Since: 3.26

### e_cache_dup_revision ()

    gchar *
    e_cache_dup_revision (ECache *cache);

#### Parameters

cache | an ECache |

#### Returns

A revision of the whole `cache` . This is meant to be used by the descendants. Free the returned pointer with `g_free()`, when no longer needed.

[transfer full]

Since: 3.26

### e_cache_set_revision ()

    void
    e_cache_set_revision (ECache *cache,
                          const gchar *revision);

Sets the `revision` of the whole `cache` . This is not meant to be used by the descendants, because the revision is updated automatically when needed. The descendants can listen to "revision-changed" signal.

#### Parameters

cache | an ECache |
revision | a revision to set; use `NULL` to unset it. | [nullable]

Since: 3.26

### e_cache_change_revision ()

    void
    e_cache_change_revision (ECache *cache);

Instructs the `cache` to change its revision. In case the revision change is frozen with `e_cache_freeze_revision_change()` it notes to change the revision once the revision change is fully thaw.

#### Parameters

cache | an ECache |

Since: 3.26

### e_cache_freeze_revision_change ()

    void
    e_cache_freeze_revision_change (ECache *cache);

Freezes automatic revision change for the `cache` . The function can be called multiple times, but each such call requires its pair function `e_cache_thaw_revision_change()` call. See also `e_cache_change_revision()`.

#### Parameters

cache | an ECache |

Since: 3.26

### e_cache_thaw_revision_change ()

    void
    e_cache_thaw_revision_change (ECache *cache);

Thaws automatic revision change for the `cache` . It's the pair function of `e_cache_freeze_revision_change()`.

#### Parameters

cache | an ECache |

Since: 3.26

### e_cache_is_revision_change_frozen ()

    gboolean
    e_cache_is_revision_change_frozen (ECache *cache);

#### Parameters

cache | an ECache |

#### Returns

Whether automatic revision change for the `cache` is currently frozen.

Since: 3.26

### e_cache_erase ()

    void
    e_cache_erase (ECache *cache);

Erases the cache and all of its content from the disk. The only valid operation after this is to free the `cache` .

#### Parameters

cache | an ECache |

Since: 3.26

### e_cache_contains ()

    gboolean
    e_cache_contains (ECache *cache,
                      const gchar *uid,
                      ECacheDeletedFlag deleted_flag);

Checkes whether the `cache` contains an object with the given `uid` .

#### Parameters

cache | an ECache |
uid | a unique identifier of an object |
deleted_flag | one of ECacheDeletedFlag enum |

#### Returns

Whether the object had been found.

Since: 3.26

### e_cache_get ()

    gchar *
    e_cache_get (ECache *cache,
                 const gchar *uid,
                 gchar **out_revision,
                 ECacheColumnValues **out_other_columns,
                 GCancellable *cancellable,
                 GError **error);

Returns an object with the given `uid` . This function does not consider locally deleted objects. The `out_revision` is set to the object revision, if not `NULL`. Free it with `g_free()` when no longer needed. Similarly the `out_other_columns` contains a column name to column value strings for additional columns which had been requested when calling `e_cache_initialize_sync()`, if not `NULL`. Free the returned ECacheColumnValues with `e_cache_column_values_free()`, when no longer needed.

#### Parameters

cache | an ECache |
uid | a unique identifier of an object |
out_revision | an out variable for a revision of the object, or `NULL` to ignore. | [out][nullable][transfer full]
out_other_columns | an out variable for ECacheColumnValues other columns, as defined when creating the `cache` , or `NULL` to ignore. | [out][nullable][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

An object with the given `uid` . Free it with `g_free()`, when no longer needed. Returns `NULL` on error, like when the object could not be found.

[nullable][transfer full]

Since: 3.26

### e_cache_get_object_include_deleted ()

    gchar *
    e_cache_get_object_include_deleted (ECache *cache,
                                        const gchar *uid,
                                        gchar **out_revision,
                                        ECacheColumnValues **out_other_columns,
                                        GCancellable *cancellable,
                                        GError **error);

The same as `e_cache_get()`, only considers also locally deleted objects.

#### Parameters

cache | an ECache |
uid | a unique identifier of an object |
out_revision | an out variable for a revision of the object, or `NULL` to ignore. | [out][nullable][transfer full]
out_other_columns | an out variable for ECacheColumnValues other columns, as defined when creating the `cache` , or `NULL` to ignore. | [out][nullable][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

An object with the given `uid` . Free it with `g_free()`, when no longer needed. Returns `NULL` on error, like when the object could not be found.

[nullable][transfer full]

Since: 3.30

### e_cache_put ()

    gboolean
    e_cache_put (ECache *cache,
                 const gchar *uid,
                 const gchar *revision,
                 const gchar *object,
                 ECacheColumnValues *other_columns,
                 ECacheOfflineFlag offline_flag,
                 GCancellable *cancellable,
                 GError **error);

Stores an object into the cache. Depending on `offline_flag` , this update the object's offline state accordingly. When the `offline_flag` is set to `E_CACHE_IS_ONLINE`, then it's set to E_OFFLINE_STATE_SYNCED, like to be fully synchronized with the server, regardless of its previous offline state. Overwriting locally deleted object behaves like an addition of a completely new object.

#### Parameters

cache | an ECache |
uid | a unique identifier of an object |
revision | a revision of the object. | [nullable]
object | the object itself |
other_columns | an ECacheColumnValues with other columns to set; can be `NULL`. | [nullable]
offline_flag | one of ECacheOfflineFlag, whether putting this object in offline |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_remove ()

    gboolean
    e_cache_remove (ECache *cache,
                    const gchar *uid,
                    ECacheOfflineFlag offline_flag,
                    GCancellable *cancellable,
                    GError **error);

Removes the object with the given `uid` from the `cache` . Based on the `offline_flag` , it can remove also any information about locally made offline changes. Removing the object with `E_CACHE_IS_OFFLINE` will still remember it for later use with `e_cache_get_offline_changes()`.

#### Parameters

cache | an ECache |
uid | a unique identifier of an object |
offline_flag | one of ECacheOfflineFlag, whether removing the object in offline |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_remove_all ()

    gboolean
    e_cache_remove_all (ECache *cache,
                        GCancellable *cancellable,
                        GError **error);

Removes all objects from the `cache` in one call.

#### Parameters

cache | an ECache |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_get_count ()

    guint
    e_cache_get_count (ECache *cache,
                       ECacheDeletedFlag deleted_flag,
                       GCancellable *cancellable,
                       GError **error);

#### Parameters

cache | an ECache |
deleted_flag | one of ECacheDeletedFlag enum |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Count of objects stored in the `cache` .

Since: 3.26

### e_cache_get_uids ()

    gboolean
    e_cache_get_uids (ECache *cache,
                      ECacheDeletedFlag deleted_flag,
                      GSList **out_uids,
                      GSList **out_revisions,
                      GCancellable *cancellable,
                      GError **error);

Gets a list of unique object identifiers stored in the `cache` , optionally together with their revisions. The uids are not returned in any particular order, but the position between `out_uids` and `out_revisions` matches the same object.

Both `out_uids` and `out_revisions` contain newly allocated GSList, which should be freed with g_slist_free_full (slist, g_free); when no longer needed.

#### Parameters

cache | an ECache |
deleted_flag | one of ECacheDeletedFlag enum |
out_uids | a pointer to GSList to store the found uid to. | [out][transfer full][element-type utf8]
out_revisions | a pointer to GSList to store the found revisions to, or `NULL`. | [out][transfer full][element-type utf8][nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded. It doesn't necessarily mean that there was any object stored in the `cache` .

Since: 3.26

### e_cache_get_objects ()

    gboolean
    e_cache_get_objects (ECache *cache,
                         ECacheDeletedFlag deleted_flag,
                         GSList **out_objects,
                         GSList **out_revisions,
                         GCancellable *cancellable,
                         GError **error);

Gets a list of objects stored in the `cache` , optionally together with their revisions. The uids are not returned in any particular order, but the position between `out_objects` and `out_revisions` matches the same object.

Both `out_objects` and `out_revisions` contain newly allocated GSList, which should be freed with g_slist_free_full (slist, g_free); when no longer needed.

#### Parameters

cache | an ECache |
deleted_flag | one of ECacheDeletedFlag enum |
out_objects | a pointer to GSList to store the found objects to. | [out][transfer full][element-type utf8]
out_revisions | a pointer to GSList to store the found revisions to, or `NULL`. | [out][transfer full][element-type utf8][nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded. It doesn't necessarily mean that there was any object stored in the `cache` .

Since: 3.26

### e_cache_foreach ()

    gboolean
    e_cache_foreach (ECache *cache,
                     ECacheDeletedFlag deleted_flag,
                     const gchar *where_clause,
                     ECacheForeachFunc func,
                     gpointer user_data,
                     GCancellable *cancellable,
                     GError **error);

Calls `func` for each found object, which satisfies the criteria for both `deleted_flag` and `where_clause` .

Note the `func` should not call any SQLite commands, because it's invoked within a SELECT statement execution.

#### Parameters

cache | an ECache |
deleted_flag | one of ECacheDeletedFlag enum |
where_clause | an optional SQLite WHERE clause part, or `NULL`. | [nullable]
func | an ECacheForeachFunc function to call for each object. | [scope call]
user_data | user data for the `func` |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_foreach_update ()

    gboolean
    e_cache_foreach_update (ECache *cache,
                            ECacheDeletedFlag deleted_flag,
                            const gchar *where_clause,
                            ECacheUpdateFunc func,
                            gpointer user_data,
                            GCancellable *cancellable,
                            GError **error);

Calls `func` for each found object, which satisfies the criteria for both `deleted_flag` and `where_clause` , letting the caller update values where necessary. The return value of `func` is used to determine whether the call was successful, not whether there are any changes to be saved. If anything fails during the call then the all changes are reverted.

When there are requested any changes by the `func` , this function also calls `e_cache_copy_missing_to_column_values()` to ensure no descendant column data is lost.

#### Parameters

cache | an ECache |
deleted_flag | one of ECacheDeletedFlag enum |
where_clause | an optional SQLite WHERE clause part, or `NULL`. | [nullable]
func | an ECacheUpdateFunc function to call for each object. | [scope call]
user_data | user data for the `func` |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_copy_missing_to_column_values ()

    void
    e_cache_copy_missing_to_column_values (ECache *cache,
                                           gint ncols,
                                           const gchar *column_names[],
                                           const gchar *column_values[],
                                           ECacheColumnValues *other_columns);

Adds every column value which is not part of the `other_columns` to it, except of E_CACHE_COLUMN_UID, E_CACHE_COLUMN_REVISION, E_CACHE_COLUMN_OBJECT and E_CACHE_COLUMN_STATE columns.

This can be used within the callback of `e_cache_foreach_update()`.

#### Parameters

cache | an ECache |
ncols | count of columns, items in column_names and column_values |
column_names | column names. | [array length=ncols][element-type utf8]
column_values | column values. | [array length=ncols][element-type utf8]
other_columns | an ECacheColumnValues to fill. | [inout]

Since: 3.32

### e_cache_get_offline_state ()

    EOfflineState
    e_cache_get_offline_state (ECache *cache,
                               const gchar *uid,
                               GCancellable *cancellable,
                               GError **error);

#### Parameters

cache | an ECache |
uid | a unique identifier of an object |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Current offline state EOfflineState for the given object. It returns `E_OFFLINE_STATE_UNKNOWN` when the object could not be found or other error happened.

Since: 3.26

### e_cache_set_offline_state ()

    gboolean
    e_cache_set_offline_state (ECache *cache,
                               const gchar *uid,
                               EOfflineState state,
                               GCancellable *cancellable,
                               GError **error);

Sets an offline `state` for the object identified by `uid` .

#### Parameters

cache | an ECache |
uid | a unique identifier of an object |
state | an EOfflineState to set |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_get_offline_changes ()

    GSList *
    e_cache_get_offline_changes (ECache *cache,
                                 GCancellable *cancellable,
                                 GError **error);

Gathers the list of all offline changes being done so far. The returned GSList contains ECacheOfflineChange structure. Use `e_cache_clear_offline_changes()` to clear all offline changes at once.

#### Parameters

cache | an ECache |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

A newly allocated list of all offline changes. Free it with g_slist_free_full (slist, e_cache_offline_change_free); when no longer needed.

[transfer full][element-type ECacheOfflineChange]

Since: 3.26

### e_cache_clear_offline_changes ()

    gboolean
    e_cache_clear_offline_changes (ECache *cache,
                                   GCancellable *cancellable,
                                   GError **error);

Marks all objects as being fully synchronized with the server and removes those which are marked as locally deleted.

#### Parameters

cache | an ECache |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_set_key ()

    gboolean
    e_cache_set_key (ECache *cache,
                     const gchar *key,
                     const gchar *value,
                     GError **error);

Sets a `value` of the user `key` , or deletes it, if the `value` is `NULL`.

#### Parameters

cache | an ECache |
key | a key name |
value | a value to set, or `NULL` to delete the key. | [nullable]
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_dup_key ()

    gchar *
    e_cache_dup_key (ECache *cache,
                     const gchar *key,
                     GError **error);

#### Parameters

cache | an ECache |
key | a key name |
error | return location for a GError, or `NULL` |

#### Returns

a value of the `key` . Free the returned string with `g_free()`, when no longer needed.

[transfer full]

Since: 3.26

### e_cache_set_key_int ()

    gboolean
    e_cache_set_key_int (ECache *cache,
                         const gchar *key,
                         gint value,
                         GError **error);

Sets an integer `value` for the user `key` .

#### Parameters

cache | an ECache |
key | a key name |
value | an integer value to set |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_get_key_int ()

    gint
    e_cache_get_key_int (ECache *cache,
                         const gchar *key,
                         GError **error);

Reads the user `key` value as an integer.

#### Parameters

cache | an ECache |
key | a key name |
error | return location for a GError, or `NULL` |

#### Returns

The user `key` value or -1 on error.

Since: 3.26

### e_cache_lock ()

    void
    e_cache_lock (ECache *cache,
                  ECacheLockType lock_type);

Locks the `cache` thus other threads cannot use it. This can be called recursively within one thread. Each call should have its pair `e_cache_unlock()`.

#### Parameters

cache | an ECache |
lock_type | an ECacheLockType |

Since: 3.26

### e_cache_unlock ()

    void
    e_cache_unlock (ECache *cache,
                    ECacheUnlockAction action);

Unlocks the cache which was previouly locked with `e_cache_lock()`. The cache locked with E_CACHE_LOCK_WRITE should use either `action` E_CACHE_UNLOCK_COMMIT or E_CACHE_UNLOCK_ROLLBACK, while the E_CACHE_LOCK_READ should use E_CACHE_UNLOCK_NONE `action` .

#### Parameters

cache | an ECache |
action | an ECacheUnlockAction |

Since: 3.26

### e_cache_get_sqlitedb ()

    gpointer
    e_cache_get_sqlitedb (ECache *cache);

#### Parameters

cache | an ECache |

#### Returns

An SQLite3 database pointer. It is owned by the `cache` .

[transfer none]

Since: 3.26

### e_cache_sqlite_exec ()

    gboolean
    e_cache_sqlite_exec (ECache *cache,
                         const gchar *sql_stmt,
                         GCancellable *cancellable,
                         GError **error);

Executes an SQLite statement. Use `e_cache_sqlite_select()` for SELECT statements.

#### Parameters

cache | an ECache |
sql_stmt | an SQLite statement to execute |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_sqlite_select ()

    gboolean
    e_cache_sqlite_select (ECache *cache,
                           const gchar *sql_stmt,
                           ECacheSelectFunc func,
                           gpointer user_data,
                           GCancellable *cancellable,
                           GError **error);

Executes a SELECT statement `sql_stmt` and calls `func` for each row of the result. Use `e_cache_sqlite_exec()` for statements which do not return row sets.

#### Parameters

cache | an ECache |
sql_stmt | an SQLite SELECT statement to execute |
func | an ECacheSelectFunc function to call for each row. | [scope call]
user_data | user data for `func` |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cache_sqlite_maybe_vacuum ()

    gboolean
    e_cache_sqlite_maybe_vacuum (ECache *cache,
                                 GCancellable *cancellable,
                                 GError **error);

Runs vacuum (compacts the database file), if needed.

#### Parameters

cache | an ECache |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded. It doesn't mean that the vacuum had been run, only that no error happened during the call.

Since: 3.26

### e_cache_sqlite_stmt_append_printf ()

    void
    e_cache_sqlite_stmt_append_printf (GString *stmt,
                                       const gchar *format,
                                       ...);

Appends an SQLite statement fragment based on the `format` and its arguments to the `stmt` . The `format` can contain any values recognized by `sqlite3_mprintf()`.

#### Parameters

stmt | a GString statement to append to |
format | a printf-like format |
... | arguments for the `format` |

Since: 3.26

### e_cache_sqlite_stmt_printf ()

    gchar *
    e_cache_sqlite_stmt_printf (const gchar *format,
                                ...);

Creates an SQLite statement based on the `format` and its arguments. The `format` can contain any values recognized by `sqlite3_mprintf()`.

#### Parameters

format | a printf-like format |
... | arguments for the `format` |

#### Returns

A new SQLite statement. Free the returned string with `e_cache_sqlite_stmt_free()` when no longer needed.

[transfer full]

Since: 3.26

### e_cache_sqlite_stmt_free ()

    void
    e_cache_sqlite_stmt_free (gchar *stmt);

Frees a statement previously constructed with `e_cache_sqlite_stmt_printf()`.

#### Parameters

stmt | a statement to free |

Since: 3.26

## Types and Values

### E_CACHE_TABLE_OBJECTS

    #define E_CACHE_TABLE_OBJECTS "ECacheObjects"

### E_CACHE_TABLE_KEYS

    #define E_CACHE_TABLE_KEYS "ECacheKeys"

### E_CACHE_COLUMN_UID

    #define E_CACHE_COLUMN_UID "ECacheUID"

### E_CACHE_COLUMN_REVISION

    #define E_CACHE_COLUMN_REVISION "ECacheREV"

### E_CACHE_COLUMN_OBJECT

    #define E_CACHE_COLUMN_OBJECT "ECacheOBJ"

### E_CACHE_COLUMN_STATE

    #define E_CACHE_COLUMN_STATE "ECacheState"

### E_CACHE_ERROR

    #define E_CACHE_ERROR (e_cache_error_quark ())

Error domain for ECache operations.

Since: 3.26

### enum ECacheError

Defines the types of possible errors reported by the ECache

#### Members

E_CACHE_ERROR_ENGINE | An error was reported from the SQLite engine |
E_CACHE_ERROR_CONSTRAINT | The error occurred due to an explicit constraint, like when attempting to add two objects with the same UID. |
E_CACHE_ERROR_NOT_FOUND | An object was not found by UID (this is different from a query that returns no results, which is not an error). |
E_CACHE_ERROR_INVALID_QUERY | A query was invalid. |
E_CACHE_ERROR_UNSUPPORTED_FIELD | A field requested for inclusion in summary is not supported. |
E_CACHE_ERROR_UNSUPPORTED_QUERY | A query was not supported. |
E_CACHE_ERROR_END_OF_LIST | An attempt was made to fetch results past the end of a the list. |
E_CACHE_ERROR_LOAD | An error occured while loading or creating the database. |

Since: 3.26

### ECacheOfflineChange

    typedef struct {
    	gchar *uid;
    	gchar *revision;
    	gchar *object;
    	EOfflineState state;
    } ECacheOfflineChange;

Holds the information about offline change for one object.

#### Members

gchar *`uid`; | UID of the object |
gchar *`revision`; | stored revision of the object |
gchar *`object`; | the object itself |
EOfflineState `state`; | an EOfflineState of the object |

Since: 3.26

### enum ECacheLockType

Indicates the type of lock requested in `e_cache_lock()`.

#### Members

E_CACHE_LOCK_READ | Obtain a lock for reading. |
E_CACHE_LOCK_WRITE | Obtain a lock for writing. This also starts a transaction. |

Since: 3.26

### enum ECacheUnlockAction

Indicates what type of action to take while unlocking the cache with `e_cache_unlock()`.

#### Members

E_CACHE_UNLOCK_NONE | Just unlock, this is appropriate for locks which were obtained with `E_CACHE_LOCK_READ`. |
E_CACHE_UNLOCK_COMMIT | Commit any modifications which were made while the lock was held. |
E_CACHE_UNLOCK_ROLLBACK | Rollback any modifications which were made while the lock was held. |

Since: 3.26

### enum ECacheDeletedFlag

Declares whether to exclude or include locally deleted objects.

#### Members

E_CACHE_EXCLUDE_DELETED | Do not include locally deleted objects |
E_CACHE_INCLUDE_DELETED | Include locally deleted objects |

Since: 3.26

### enum ECacheOfflineFlag

Declares whether the operation is done in online or offline. This influences the offline state of the related objects.

#### Members

E_CACHE_OFFLINE_UNKNOWN | Do not know current online/offline state |
E_CACHE_IS_ONLINE | The operation is done in online |
E_CACHE_IS_OFFLINE | The operation is done in offline |

Since: 3.26

### struct ECache

    struct ECache;

Contains only private data that should be read and manipulated using the functions below.

Since: 3.26

## Signal Details

### The `“before-put”` signal

    gboolean
    user_function (ECache             *ecache,
                   char               *arg1,
                   char               *arg2,
                   char               *arg3,
                   ECacheColumnValues *arg4,
                   gboolean            arg5,
                   GCancellable       *arg6,
                   gpointer            arg7,
                   gpointer            user_data)

Flags: Run Last

### The `“before-remove”` signal

    gboolean
    user_function (ECache       *ecache,
                   char         *arg1,
                   GCancellable *arg2,
                   gpointer      arg3,
                   gpointer      user_data)

Flags: Run Last

### The `“revision-changed”` signal

    void
    user_function (ECache  *ecache,
                   gpointer user_data)

Flags: Run Last