ECacheKeys: Evolution-Data-Server Reference Manual

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

## Functions

gboolean | (*ECacheKeysForeachFunc) ()
ECacheKeys * | e_cache_keys_new ()
ECache * | e_cache_keys_get_cache ()
const gchar * | e_cache_keys_get_table_name ()
const gchar * | e_cache_keys_get_key_column_name ()
const gchar * | e_cache_keys_get_value_column_name ()
gboolean | e_cache_keys_init_table_sync ()
gboolean | e_cache_keys_count_keys_sync ()
gboolean | e_cache_keys_put_sync ()
gboolean | e_cache_keys_get_sync ()
gboolean | e_cache_keys_get_ref_count_sync ()
gboolean | e_cache_keys_foreach_sync ()
gboolean | e_cache_keys_remove_sync ()
gboolean | e_cache_keys_remove_all_sync ()

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