ECacheKeys

ECacheKeys — A table wrapper for key-value reference-counted data

Functions

Properties

ECache * cache Read / Write / Construct Only
char * key-column-name Read / Write / Construct Only
char * table-name Read / Write / Construct Only
char * value-column-name Read / Write / Construct Only

Signals

void changed Run Last

Types and Values

struct ECacheKeys

Object Hierarchy

    GObject
    ╰── ECacheKeys

Includes

#include <libebackend/libebackend.h>

Description

The ECacheKeys represents a table, which holds key-value data with keys being reference-counted, thus the table changes keys as they are added and removed.

Functions

ECacheKeysForeachFunc ()

gboolean
(*ECacheKeysForeachFunc) (ECacheKeys *self,
                          const gchar *key,
                          const gchar *value,
                          guint ref_count,
                          gpointer user_data);

A callback called for each row of the self table when using e_cache_keys_foreach_sync() function.

Parameters

self

an ECacheKeys

 

key

the key

 

value

the value

 

ref_count

the reference count for the key

 

user_data

user data, as used in e_cache_keys_foreach_sync()

 

Returns

TRUE to continue, FALSE to stop walk through.

Since: 3.48


e_cache_keys_new ()

ECacheKeys *
e_cache_keys_new (ECache *cache,
                  const gchar *table_name,
                  const gchar *key_column_name,
                  const gchar *value_column_name);

Creates a new ECacheKeys, which will operate with table_name , using column key_column_name to store keys and value_column_name to store values.

The created ECacheKeys doesn't hold a reference to the cache , the caller is supposed to make sure the cache won't be freed before the ECacheKeys is freed. This is to avoid circular dependency between the cache and the ECacheKeys, when the ECacheKey is created by the cache itself (which is the expected use case).

Parameters

cache

an ECache.

[transfer none]

table_name

a table name to operate with

 

key_column_name

column name for the keys

 

value_column_name

column name for the values

 

Returns

a new ECacheKeys.

[transfer full]

Since: 3.48


e_cache_keys_get_cache ()

ECache *
e_cache_keys_get_cache (ECacheKeys *self);

Gets an ECache, with which the self had been created.

Parameters

self

an ECacheKeys

 

Returns

an ECache.

[transfer none]

Since: 3.48


e_cache_keys_get_table_name ()

const gchar *
e_cache_keys_get_table_name (ECacheKeys *self);

Gets a table name, with which the self had been created.

Parameters

self

an ECacheKeys

 

Returns

a table name

Since: 3.48


e_cache_keys_get_key_column_name ()

const gchar *
e_cache_keys_get_key_column_name (ECacheKeys *self);

Gets a key column name, with which the self had been created.

Parameters

self

an ECacheKeys

 

Returns

a key column name

Since: 3.48


e_cache_keys_get_value_column_name ()

const gchar *
e_cache_keys_get_value_column_name (ECacheKeys *self);

Get a value column name, with which the self had been created.

Parameters

self

an ECacheKeys

 

Returns

a value column name

Since: 3.48


e_cache_keys_init_table_sync ()

gboolean
e_cache_keys_init_table_sync (ECacheKeys *self,
                              GCancellable *cancellable,
                              GError **error);

Initializes table in the corresponding ECache.

Parameters

self

an ECacheKeys

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.48


e_cache_keys_count_keys_sync ()

gboolean
e_cache_keys_count_keys_sync (ECacheKeys *self,
                              gint64 *out_n_stored,
                              GCancellable *cancellable,
                              GError **error);

Counts how many keys the self stores and set it to the out_n_stored .

Parameters

self

an ECacheKeys

 

out_n_stored

return location to set count of stored keys.

[out]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.48


e_cache_keys_put_sync ()

gboolean
e_cache_keys_put_sync (ECacheKeys *self,
                       const gchar *key,
                       const gchar *value,
                       guint inc_ref_counts,
                       GCancellable *cancellable,
                       GError **error);

Puts the key and value into the self . The function adds a new or replaces an existing key , if any such already exists in the self .

Parameters

self

an ECacheKeys

 

key

a key identifier to put

 

value

a value to put with the key

 

inc_ref_counts

how many refs to add, or 0 to have it stored forever

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.48


e_cache_keys_get_sync ()

gboolean
e_cache_keys_get_sync (ECacheKeys *self,
                       const gchar *key,
                       gchar **out_value,
                       GCancellable *cancellable,
                       GError **error);

Gets a stored value with given key , which had been previously put into the self with e_cache_keys_put_sync().

The returned string should be freed with g_free() when no longer needed.

Parameters

self

an ECacheKeys

 

key

a key to get

 

out_value

return location for the stored value for the key .

[out][transfer full]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.48


e_cache_keys_get_ref_count_sync ()

gboolean
e_cache_keys_get_ref_count_sync (ECacheKeys *self,
                                 const gchar *key,
                                 guint *out_ref_count,
                                 GCancellable *cancellable,
                                 GError **error);

Gets currently stored reference count for the key . Note the reference count can be 0, which means the key is stored forever.

Parameters

self

an ECacheKeys

 

key

a key to get reference count for

 

out_ref_count

return location for the stored reference count for the key .

[out]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.48


e_cache_keys_foreach_sync ()

gboolean
e_cache_keys_foreach_sync (ECacheKeys *self,
                           ECacheKeysForeachFunc func,
                           gpointer user_data,
                           GCancellable *cancellable,
                           GError **error);

Calls func for each stored key in the self , providing information about its value and reference count.

Parameters

self

an ECacheKeys

 

func

an ECacheKeysForeachFunc, which is called for each stored key.

[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.48


e_cache_keys_remove_sync ()

gboolean
e_cache_keys_remove_sync (ECacheKeys *self,
                          const gchar *key,
                          guint dec_ref_counts,
                          GCancellable *cancellable,
                          GError **error);

Dereferences use count of the key by dec_ref_counts and removes it from the cache when the reference count reaches zero. Special case is with dec_ref_counts is zero, in which case the key is removed regardless of the current reference count.

It's not an error when the key doesn't exist in the cache.

Parameters

self

an ECacheKeys

 

key

a key to remove/dereference

 

dec_ref_counts

reference counts to drop, 0 to remove it regardless of the current reference count

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.48


e_cache_keys_remove_all_sync ()

gboolean
e_cache_keys_remove_all_sync (ECacheKeys *self,
                              GCancellable *cancellable,
                              GError **error);

Removes all stored keys from the self .

Parameters

self

an ECacheKeys

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.48

Types and Values

struct ECacheKeys

struct ECacheKeys;

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

Since: 3.48

Property Details

The “cache” property

  “cache”                    ECache *

The ECache being used for this keys table.

Owner: ECacheKeys

Flags: Read / Write / Construct Only

Since: 3.48


The “key-column-name” property

  “key-column-name”          char *

The column name for the keys.

Owner: ECacheKeys

Flags: Read / Write / Construct Only

Default value: NULL

Since: 3.48


The “table-name” property

  “table-name”               char *

The table name of this keys table.

Owner: ECacheKeys

Flags: Read / Write / Construct Only

Default value: NULL

Since: 3.48


The “value-column-name” property

  “value-column-name”        char *

The column name for the values.

Owner: ECacheKeys

Flags: Read / Write / Construct Only

Default value: NULL

Since: 3.48

Signal Details

The “changed” signal

void
user_function (ECacheKeys *ecachekeys,
               gpointer    user_data)

A signal emitted when the stored keys changed, aka when a new key is added or when an existing key is removed. It's not emitted when only a reference count changes for a key.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.48