## ESourceBackendSummarySetup

ESourceBackendSummarySetup — ESource extension to configure summary fields

## Functions

EContactField * | e_source_backend_summary_setup_get_summary_fields ()
void | e_source_backend_summary_setup_set_summary_fieldsv ()
void | e_source_backend_summary_setup_set_summary_fields ()
EContactField * | e_source_backend_summary_setup_get_indexed_fields ()
void | e_source_backend_summary_setup_set_indexed_fieldsv ()
void | e_source_backend_summary_setup_set_indexed_fields ()

## Types and Values

#define | E_SOURCE_EXTENSION_BACKEND_SUMMARY_SETUP
struct | ESourceBackendSummarySetup
struct | ESourceBackendSummarySetupClass

## Includes

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

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

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.

## Functions

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

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

#### Parameters

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.

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

#### Parameters

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);

#### Parameters

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.

#### Parameters

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.

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.

#### Parameters

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);

#### Parameters

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

Since 3.8

## Types and Values

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