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

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