## EFileCache

EFileCache — Simple file-based hash table for strings

## Synopsis

    struct              EFileCache;
    struct              EFileCacheClass;
    EFileCache *        e_file_cache_new                    (const gchar *filename);
    gboolean            e_file_cache_remove                 (EFileCache *cache);
    gboolean            e_file_cache_clean                  (EFileCache *cache);
    const gchar *       e_file_cache_get_object             (EFileCache *cache,
                                                             const gchar *key);
    GSList *            e_file_cache_get_objects            (EFileCache *cache);
    GSList *            e_file_cache_get_keys               (EFileCache *cache);
    gboolean            e_file_cache_add_object             (EFileCache *cache,
                                                             const gchar *key,
                                                             const gchar *value);
    gboolean            e_file_cache_replace_object         (EFileCache *cache,
                                                             const gchar *key,
                                                             const gchar *new_value);
    gboolean            e_file_cache_remove_object          (EFileCache *cache,
                                                             const gchar *key);
    void                e_file_cache_freeze_changes         (EFileCache *cache);
    void                e_file_cache_thaw_changes           (EFileCache *cache);
    const gchar *       e_file_cache_get_filename           (EFileCache *cache);

## Description

An EFileCache is a simple hash table of strings backed by an XML file for permanent storage. The XML file is written to disk with every unless the cache is temporarily frozen with `e_file_cache_freeze_changes()`.

## Details

### struct EFileCache

    struct EFileCache {
    	GObject parent;
    	EFileCachePrivate *priv;
    };

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

### struct EFileCacheClass

    struct EFileCacheClass {
    	GObjectClass parent_class;
    };

### e_file_cache_new ()

    EFileCache *        e_file_cache_new                    (const gchar *filename);

Creates a new EFileCache object, which implements a cache of objects. Useful for remote backends.

`filename` : | filename where the cache is kept
Returns : | a new EFileCache

### e_file_cache_remove ()

    gboolean            e_file_cache_remove                 (EFileCache *cache);

Remove the cache from disk.

`cache` : | an EFileCache
Returns : | `TRUE` if successful, `FALSE` if a file error occurred

### e_file_cache_clean ()

    gboolean            e_file_cache_clean                  (EFileCache *cache);

Clean up the cache's contents.

`cache` : | an EFileCache
Returns : | `TRUE` always

### e_file_cache_get_object ()

    const gchar *       e_file_cache_get_object             (EFileCache *cache,
                                                             const gchar *key);

Returns the object corresponding to `key`. If no such object exists in `cache`, the function returns `NULL`.

`cache` : | an EFileCache
`key` : | the hash key of the object to find
Returns : | the object corresponding to `key`

### e_file_cache_get_objects ()

    GSList *            e_file_cache_get_objects            (EFileCache *cache);

Returns a list of objects in `cache`. The objects are owned by `cache` and must not be modified or freed. Free the returned list with `g_slist_free()`.

`cache` : | an EFileCache
Returns : | a list of objects

### e_file_cache_get_keys ()

    GSList *            e_file_cache_get_keys               (EFileCache *cache);

Returns a list of keys in `cache`. The keys are owned by `cache` and must not be modified or freed. Free the returned list with `g_slist_free()`.

`cache` : | an EFileCache
Returns : | a list of keys

### e_file_cache_add_object ()

    gboolean            e_file_cache_add_object             (EFileCache *cache,
                                                             const gchar *key,
                                                             const gchar *value);

Adds a new `key` / `value` entry to `cache`. If an object corresponding to `key` already exists in `cache`, the function returns `FALSE`.

`cache` : | an EFileCache
`key` : | the hash key of the object to add
`value` : | the object to add
Returns : | `TRUE` if successful, `FALSE` if `key` already exists

### e_file_cache_replace_object ()

    gboolean            e_file_cache_replace_object         (EFileCache *cache,
                                                             const gchar *key,
                                                             const gchar *new_value);

Replaces the object corresponding to `key` with `new_value`. If no such object exists in `cache`, the function returns `FALSE`.

`cache` : | an EFileCache
`key` : | the hash key of the object to replace
`new_value` : | the new object for `key`
Returns : | `TRUE` if successful, `FALSE` if `key` was not found

### e_file_cache_remove_object ()

    gboolean            e_file_cache_remove_object          (EFileCache *cache,
                                                             const gchar *key);

Removes the object corresponding to `key` from `cache`. If no such object exists in `cache`, the function returns `FALSE`.

`cache` : | an EFileCache
`key` : | the hash key of the object to remove
Returns : | `TRUE` if successful, `FALSE` if `key` was not found

### e_file_cache_freeze_changes ()

    void                e_file_cache_freeze_changes         (EFileCache *cache);

Disables temporarily all writes to disk for `cache`.

`cache` : | an EFileCache

### e_file_cache_thaw_changes ()

    void                e_file_cache_thaw_changes           (EFileCache *cache);

Reverts the affects of `e_file_cache_freeze_changes()`. Each change to `cache` is once again written to disk.

`cache` : | an EFileCache

### e_file_cache_get_filename ()

    const gchar *       e_file_cache_get_filename           (EFileCache *cache);

Gets the name of the file where the cache is being stored.

`cache` : | A `EFileCache` object.
Returns : | The name of the cache.