## EBookBackendCache

EBookBackendCache

## Synopsis

    struct              EBookBackendCache;
    EBookBackendCache * e_book_backend_cache_new            (const gchar *filename);
    EContact *	         e_book_backend_cache_get_contact    (EBookBackendCache *cache,
                                                             const gchar *uid);
    gboolean            e_book_backend_cache_add_contact    (EBookBackendCache *cache,
                                                             EContact *contact);
    gboolean            e_book_backend_cache_remove_contact (EBookBackendCache *cache,
                                                             const gchar *uid);
    gboolean            e_book_backend_cache_check_contact  (EBookBackendCache *cache,
                                                             const gchar *uid);
    GList *             e_book_backend_cache_get_contacts   (EBookBackendCache *cache,
                                                             const gchar *query);
    void                e_book_backend_cache_set_populated  (EBookBackendCache *cache);
    gboolean            e_book_backend_cache_is_populated   (EBookBackendCache *cache);
    void                e_book_backend_cache_set_time       (EBookBackendCache *cache,
                                                             const gchar *t);
    gchar *		           e_book_backend_cache_get_time       (EBookBackendCache *cache);
    GPtrArray *	        e_book_backend_cache_search         (EBookBackendCache *cache,
                                                             const gchar *query);

## Object Hierarchy

      GObject
       +----EFileCache
             +----EBookBackendCache

## Description

## Details

### struct EBookBackendCache

    struct EBookBackendCache;

### e_book_backend_cache_new ()

    EBookBackendCache * e_book_backend_cache_new            (const gchar *filename);

Creates a new EBookBackendCache, which implements a local cache of EContact objects, useful for remote backends.

`filename` : | file to write cached data
Returns : | a new EBookBackendCache

### e_book_backend_cache_get_contact ()

    EContact *	         e_book_backend_cache_get_contact    (EBookBackendCache *cache,
                                                             const gchar *uid);

Get a cached contact. Note that the returned EContact will be newly created, and must be unreffed by the caller when no longer needed.

`cache` : | an EBookBackendCache
`uid` : | a unique contact ID
Returns : | A cached EContact, or `NULL` if `uid` is not cached.

### e_book_backend_cache_add_contact ()

    gboolean            e_book_backend_cache_add_contact    (EBookBackendCache *cache,
                                                             EContact *contact);

Adds `contact` to `cache`.

`cache` : | an EBookBackendCache
`contact` : | an EContact
Returns : | `TRUE` if the contact was cached successfully, `FALSE` otherwise.

### e_book_backend_cache_remove_contact ()

    gboolean            e_book_backend_cache_remove_contact (EBookBackendCache *cache,
                                                             const gchar *uid);

Removes the contact identified by `uid` from `cache`.

`cache` : | an EBookBackendCache
`uid` : | a unique contact ID
Returns : | `TRUE` if the contact was found and removed, `FALSE` otherwise.

### e_book_backend_cache_check_contact ()

    gboolean            e_book_backend_cache_check_contact  (EBookBackendCache *cache,
                                                             const gchar *uid);

Checks if the contact identified by `uid` exists in `cache`.

`cache` : | an EBookBackendCache
`uid` : | a unique contact ID
Returns : | `TRUE` if the cache contains the contact, `FALSE` otherwise.

### e_book_backend_cache_get_contacts ()

    GList *             e_book_backend_cache_get_contacts   (EBookBackendCache *cache,
                                                             const gchar *query);

Returns a list of EContact elements from `cache` matching `query`. When done with the list, the caller must unref the contacts and free the list.

`cache` : | an EBookBackendCache
`query` : | an s-expression
Returns : | A GList of pointers to EContact.

### e_book_backend_cache_set_populated ()

    void                e_book_backend_cache_set_populated  (EBookBackendCache *cache);

Flags `cache` as being populated - that is, it is up-to-date on the contents of the book it's caching.

`cache` : | an EBookBackendCache

### e_book_backend_cache_is_populated ()

    gboolean            e_book_backend_cache_is_populated   (EBookBackendCache *cache);

Checks if `cache` is populated.

`cache` : | an EBookBackendCache
Returns : | `TRUE` if `cache` is populated, `FALSE` otherwise.

### e_book_backend_cache_set_time ()

    void                e_book_backend_cache_set_time       (EBookBackendCache *cache,
                                                             const gchar *t);

### e_book_backend_cache_get_time ()

    gchar *		           e_book_backend_cache_get_time       (EBookBackendCache *cache);

### e_book_backend_cache_search ()

    GPtrArray *	        e_book_backend_cache_search         (EBookBackendCache *cache,
                                                             const gchar *query);

Returns an array of pointers to unique contact ID strings for contacts in `cache` matching `query`. When done with the array, the caller must free the ID strings and the array.

`cache` : | an EBookBackendCache
`query` : | an s-expression
Returns : | A GPtrArray of pointers to contact ID strings.