## ESourceBackendSummarySetup

ESourceBackendSummarySetup — ESource extension to configure summary fields

## Synopsis

    #include <libebook-contacts/libebook-contacts.h>

    #define             E_SOURCE_EXTENSION_BACKEND_SUMMARY_SETUP
    struct              ESourceBackendSummarySetup;
    struct              ESourceBackendSummarySetupClass;
    EContactField *     e_source_backend_summary_setup_get_summary_fields
                                                            (ESourceBackendSummarySetup *extension,
                                                             gint *n_fields);
    void                e_source_backend_summary_setup_set_summary_fieldsv
                                                            (ESourceBackendSummarySetup *extension,
                                                             EContactField *fields,
                                                             gint n_fields);
    void                e_source_backend_summary_setup_set_summary_fields
                                                            (ESourceBackendSummarySetup *extension,
                                                             ...);
    EContactField *     e_source_backend_summary_setup_get_indexed_fields
                                                            (ESourceBackendSummarySetup *extension,
                                                             EBookIndexType **types,
                                                             gint *n_fields);
    void                e_source_backend_summary_setup_set_indexed_fieldsv
                                                            (ESourceBackendSummarySetup *extension,
                                                             EContactField *fields,
                                                             EBookIndexType *types,
                                                             gint n_fields);
    void                e_source_backend_summary_setup_set_indexed_fields
                                                            (ESourceBackendSummarySetup *extension,
                                                             ...);

## Description

The ESourceBackendSummarySetup extension configures which EContactFields should be in the summary and which of those fields should be optimized for quicker search results.

Access the extension as follows:

    1
    2
    3
    4
    5

    #include <libebook-contacts/libebook-contacts.h>

    ESourceBackendSummarySetup *extension;

    extension = e_source_get_extension (source, E_SOURCE_EXTENSION_BACKEND_SUMMARY_SETUP);

### Note

The summary configuration is expected to be setup in only one way for a given ESource at creation time. Any configurations made after creation of the book in question will be ignored.

## Details

### E_SOURCE_EXTENSION_BACKEND_SUMMARY_SETUP

    #define E_SOURCE_EXTENSION_BACKEND_SUMMARY_SETUP "Backend Summary Setup"

Pass this extension name to `e_source_get_extension()` to access ESourceBackendSummarySetup. This is also used as a group name in key files.

Since 3.8

### struct ESourceBackendSummarySetup

    struct ESourceBackendSummarySetup {
    	ESourceBackend parent;
    	ESourceBackendSummarySetupPrivate *priv;
    };

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

Since 3.8

### struct ESourceBackendSummarySetupClass

    struct ESourceBackendSummarySetupClass {
    	ESourceBackendClass parent_class;
    };

### e_source_backend_summary_setup_get_summary_fields ()

    EContactField *     e_source_backend_summary_setup_get_summary_fields
                                                            (ESourceBackendSummarySetup *extension,
                                                             gint *n_fields);

Fetches the EContactFields which are configured to be a part of the summary.

### Note

If there are no configured summary fields, the default configuration is assumed

`extension` : | An ESourceBackendSummarySetup
`n_fields` : | A return location for the number of EContactFields in the returned array. [out]
Returns : | An array of EContactFields `n_fields` long, should be freed with `g_free()` when done. [transfer full]

Since 3.8

### e_source_backend_summary_setup_set_summary_fieldsv ()

    void                e_source_backend_summary_setup_set_summary_fieldsv
                                                            (ESourceBackendSummarySetup *extension,
                                                             EContactField *fields,
                                                             gint n_fields);

Sets the summary fields configured for the given addressbook.

The fields `E_CONTACT_UID` and `E_CONTACT_REV` are not optional, they will be stored in the summary regardless of the configured summary.

An empty summary configuration is assumed to be the default summary configuration.

### Note

Only EContactFields with the type G_TYPE_STRING or G_TYPE_BOOLEAN are currently supported as summary fields.

`extension` : | An ESourceBackendSummarySetup
`fields` : | The array of EContactFields to set as summary fields
`n_fields` : | The number of EContactFields in `fields`

Since 3.8

### e_source_backend_summary_setup_set_summary_fields ()

    void                e_source_backend_summary_setup_set_summary_fields
                                                            (ESourceBackendSummarySetup *extension,
                                                             ...);

Like `e_source_backend_summary_setup_set_summary_fieldsv()`, but takes a literal list of EContactFields for convenience.

To configure the address book summary fields with main phone nubmer fields:

    1
    2
    3
    4
    5
    6
    7

    #include <libebook/libebook.h>

    ESourceBackendSummarySetup *extension;

    extension = e_source_get_extension (source, E_SOURCE_EXTENSION_BACKEND_SUMMARY_SETUP);

    e_source_backend_summary_setup_set_summary_fields (extension, E_CONTACT_FULL_NAME, E_CONTACT_EMAIL, 0);

`extension` : | An ESourceBackendSummarySetup
`...` : | A 0 terminated list of EContactFields to set as summary fields

Since 3.8

### e_source_backend_summary_setup_get_indexed_fields ()

    EContactField *     e_source_backend_summary_setup_get_indexed_fields
                                                            (ESourceBackendSummarySetup *extension,
                                                             EBookIndexType **types,
                                                             gint *n_fields);

Fetches the EContactFields configured to be indexed, with thier respective EBookIndexTypes.

`extension` : | An ESourceBackendSummarySetup
`types` : | A return location for the set of EBookIndexTypes corresponding to each returned field, should be freed with `g_free()` when no longer needed. [out][transfer full]
`n_fields` : | The number of elements in the returned arrays. [out]
Returns : | The array of indexed EContactFields. [transfer full]

Since 3.8

### e_source_backend_summary_setup_set_indexed_fieldsv ()

    void                e_source_backend_summary_setup_set_indexed_fieldsv
                                                            (ESourceBackendSummarySetup *extension,
                                                             EContactField *fields,
                                                             EBookIndexType *types,
                                                             gint n_fields);

Defines indexes for quick reference for the given given EContactFields in the addressbook.

The same EContactField may be specified multiple times to create multiple indexes with different characteristics. If an E_BOOK_INDEX_PREFIX index is created it will be used for E_BOOK_QUERY_BEGINS_WITH queries. A E_BOOK_INDEX_SUFFIX index will be constructed efficiently for suffix matching and will be used for E_BOOK_QUERY_ENDS_WITH queries. Similar a E_BOOK_INDEX_PHONE index will optimize E_BOOK_QUERY_EQUALS_PHONE_NUMBER searches.

### Note

The specified indexed fields must also be a part of the summary, any indexed fields specified that are not already a part of the summary will be ignored.

`extension` : | An ESourceBackendSummarySetup
`fields` : | The array of EContactFields to set indexes for
`types` : | The array of EBookIndexTypes defining what types of indexes to create
`n_fields` : | The number elements in the passed `fields`, `rule_types` and `rules` arrays.

Since 3.8

### e_source_backend_summary_setup_set_indexed_fields ()

    void                e_source_backend_summary_setup_set_indexed_fields
                                                            (ESourceBackendSummarySetup *extension,
                                                             ...);

Like `e_source_backend_summary_setup_set_indexed_fieldsv()`, but takes a literal list of of indexes.

To give the 'fullname' field an index for prefix and suffix searches:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

    #include <libebook/libebook.h>

    ESourceBackendSummarySetup *extension;

    extension = e_source_get_extension (source, E_SOURCE_EXTENSION_BACKEND_SUMMARY_SETUP);

    e_source_backend_summary_setup_set_indexed_fields (extension,
                                                       E_CONTACT_FULL_NAME, E_BOOK_INDEX_PREFIX,
                                                       E_CONTACT_FULL_NAME, E_BOOK_INDEX_SUFFIX,
                                                       0);

`extension` : | An ESourceBackendSummarySetup
`...` : | A list of EContactFields, EBookIndexType pairs terminated by 0.

Since 3.8