## EBookBackendSummary

EBookBackendSummary

## Synopsis

    struct              EBookBackendSummary;
    EBookBackendSummary* e_book_backend_summary_new         (const char *summary_path,
                                                             int flush_timeout_millis);
    gboolean            e_book_backend_summary_load         (EBookBackendSummary *summary);
    gboolean            e_book_backend_summary_save         (EBookBackendSummary *summary);
    void                e_book_backend_summary_add_contact  (EBookBackendSummary *summary,
                                                             EContact *contact);
    void                e_book_backend_summary_remove_contact
                                                            (EBookBackendSummary *summary,
                                                             const char *id);
    gboolean            e_book_backend_summary_check_contact
                                                            (EBookBackendSummary *summary,
                                                             const char *id);
    void                e_book_backend_summary_touch        (EBookBackendSummary *summary);
    gboolean            e_book_backend_summary_is_up_to_date
                                                            (EBookBackendSummary *summary,
                                                             time_t t);
    gboolean            e_book_backend_summary_is_summary_query
                                                            (EBookBackendSummary *summary,
                                                             const char *query);
    GPtrArray*          e_book_backend_summary_search       (EBookBackendSummary *summary,
                                                             const char *query);
    char*               e_book_backend_summary_get_summary_vcard
                                                            (EBookBackendSummary *summary,
                                                             const char *id);

## Object Hierarchy

      GObject
       +----EBookBackendSummary

## Description

## Details

### struct EBookBackendSummary

    struct EBookBackendSummary;

### e_book_backend_summary_new ()

    EBookBackendSummary* e_book_backend_summary_new         (const char *summary_path,
                                                             int flush_timeout_millis);

Creates an EBookBackendSummary object without loading it or otherwise affecting the file. `flush_timeout_millis` specifies how much time should elapse, at a minimum, from the summary is changed until it is flushed to disk.

`summary_path` : | a local file system path
`flush_timeout_millis` : | a flush interval, in milliseconds
Returns : | A new EBookBackendSummary.

### e_book_backend_summary_load ()

    gboolean            e_book_backend_summary_load         (EBookBackendSummary *summary);

Attempts to load `summary` from disk. The load is successful if the file was located, it was in the correct format, and it was not out of date.

`summary` : | an EBookBackendSummary
Returns : | `TRUE` if the load succeeded, `FALSE` if it failed.

### e_book_backend_summary_save ()

    gboolean            e_book_backend_summary_save         (EBookBackendSummary *summary);

Attempts to save `summary` to disk.

`summary` : | an EBookBackendSummary
Returns : | `TRUE` if the save succeeded, `FALSE` otherwise.

### e_book_backend_summary_add_contact ()

    void                e_book_backend_summary_add_contact  (EBookBackendSummary *summary,
                                                             EContact *contact);

Adds a summary of `contact` to `summary`. Does not check if the contact already has a summary.

`summary` : | an EBookBackendSummary
`contact` : | an EContact to add

### e_book_backend_summary_remove_contact ()

    void                e_book_backend_summary_remove_contact
                                                            (EBookBackendSummary *summary,
                                                             const char *id);

Removes the summary of the contact identified by `id` from `summary`.

`summary` : | an EBookBackendSummary
`id` : | a unique contact ID string

### e_book_backend_summary_check_contact ()

    gboolean            e_book_backend_summary_check_contact
                                                            (EBookBackendSummary *summary,
                                                             const char *id);

Checks if a summary of the contact identified by `id` exists in `summary`.

`summary` : | an EBookBackendSummary
`id` : | a unique contact ID string
Returns : | `TRUE` if the summary exists, `FALSE` otherwise.

### e_book_backend_summary_touch ()

    void                e_book_backend_summary_touch        (EBookBackendSummary *summary);

Indicates that `summary` has changed and should be flushed to disk.

`summary` : | an EBookBackendSummary

### e_book_backend_summary_is_up_to_date ()

    gboolean            e_book_backend_summary_is_up_to_date
                                                            (EBookBackendSummary *summary,
                                                             time_t t);

Checks if `summary` is more recent than `t`.

`summary` : | an EBookBackendSummary
`t` : | the time to compare with
Returns : | `TRUE` if the summary is up to date, `FALSE` otherwise.

### e_book_backend_summary_is_summary_query ()

    gboolean            e_book_backend_summary_is_summary_query
                                                            (EBookBackendSummary *summary,
                                                             const char *query);

Checks if `query` can be satisfied by searching only the fields stored by `summary`.

`summary` : | an EBookBackendSummary
`query` : | an s-expression to check
Returns : | `TRUE` if the query can be satisfied, `FALSE` otherwise.

### e_book_backend_summary_search ()

    GPtrArray*          e_book_backend_summary_search       (EBookBackendSummary *summary,
                                                             const char *query);

Searches `summary` for contacts matching `query`.

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

### e_book_backend_summary_get_summary_vcard ()

    char*               e_book_backend_summary_get_summary_vcard
                                                            (EBookBackendSummary *summary,
                                                             const char *id);

Constructs and returns a VCard from the contact summary specified by `id`.

`summary` : | an EBookBackendSummary
`id` : | a unique contact ID
Returns : | A new VCard, or `NULL` if the contact summary didn't exist.