## ESourceList

ESourceList

## Synopsis

    struct              ESourceList;
    ESourceList *       e_source_list_new                   (void);
    ESourceList *       e_source_list_new_for_gconf         (GConfClient *client,
                                                             const gchar *path);
    ESourceList *       e_source_list_new_for_gconf_default (const gchar *path);
    GSList *            e_source_list_peek_groups           (ESourceList *list);
    ESourceGroup *      e_source_list_peek_group_by_uid     (ESourceList *list,
                                                             const gchar *uid);
    ESourceGroup *      e_source_list_peek_group_by_base_uri
                                                            (ESourceList *list,
                                                             const gchar *base_uri);
    ESourceGroup *      e_source_list_peek_group_by_properties
                                                            (ESourceList *list,
                                                             const gchar *property_name,
                                                             ...);
    ESource *           e_source_list_peek_source_by_uid    (ESourceList *list,
                                                             const gchar *uid);
    ESource *           e_source_list_peek_source_any       (ESourceList *list);
    ESource *           e_source_list_peek_default_source   (ESourceList *list);
    gboolean            e_source_list_add_group             (ESourceList *list,
                                                             ESourceGroup *group,
                                                             gint position);
    gboolean            e_source_list_remove_group          (ESourceList *list,
                                                             ESourceGroup *group);
    gboolean            e_source_list_remove_group_by_uid   (ESourceList *list,
                                                             const gchar *uid);
    ESourceGroup *      e_source_list_ensure_group          (ESourceList *list,
                                                             const gchar *name,
                                                             const gchar *base_uri,
                                                             gboolean ret_it);
    gboolean            e_source_list_remove_group_by_base_uri
                                                            (ESourceList *list,
                                                             const gchar *base_uri);
    gboolean            e_source_list_remove_source_by_uid  (ESourceList *list,
                                                             const gchar *uidj);
    gboolean            e_source_list_sync                  (ESourceList *list,
                                                             GError **error);
    gboolean            e_source_list_is_gconf_updated      (ESourceList *list);

## Object Hierarchy

      GObject
       +----ESourceList

## Signals

      "changed"                                        : Run Last
      "group-added"                                    : Run Last
      "group-removed"                                  : Run Last

## Description

## Details

### struct ESourceList

    struct ESourceList;

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

### e_source_list_new ()

    ESourceList *       e_source_list_new                   (void);

### e_source_list_new_for_gconf ()

    ESourceList *       e_source_list_new_for_gconf         (GConfClient *client,
                                                             const gchar *path);

### e_source_list_new_for_gconf_default ()

    ESourceList *       e_source_list_new_for_gconf_default (const gchar *path);

### e_source_list_peek_groups ()

    GSList *            e_source_list_peek_groups           (ESourceList *list);

Returns : | . [transfer none][element-type ESourceGroup]

### e_source_list_peek_group_by_uid ()

    ESourceGroup *      e_source_list_peek_group_by_uid     (ESourceList *list,
                                                             const gchar *uid);

Returns : | the ESourceGroup. [transfer none]

### e_source_list_peek_group_by_base_uri ()

    ESourceGroup *      e_source_list_peek_group_by_base_uri
                                                            (ESourceList *list,
                                                             const gchar *base_uri);

Returns the first ESourceGroup having the given base URI. The base URI is usually just the URI scheme, such as "http://". If no such group is present in `list`, the function returns `NULL`.

`list` : | an ESourceList
`base_uri` : | a group base URI
Returns : | an ESourceGroup with a matching base URI, or `NULL`. [transfer none]

Since 2.28

### e_source_list_peek_group_by_properties ()

    ESourceGroup *      e_source_list_peek_group_by_properties
                                                            (ESourceList *list,
                                                             const gchar *property_name,
                                                             ...);

Peeks group by its properties. Parameters are pairs of strings property_name, property_value, terminated by NULL! ESourceGroup is returned only if matches all the properties. Values are compared case insensitively.

Returns : | the ESourceGroup. [transfer none]

Since 2.28

### e_source_list_peek_source_by_uid ()

    ESource *           e_source_list_peek_source_by_uid    (ESourceList *list,
                                                             const gchar *uid);

Returns : | the ESource. [transfer none]

### e_source_list_peek_source_any ()

    ESource *           e_source_list_peek_source_any       (ESourceList *list);

Returns : | the ESource. [transfer none]

### e_source_list_peek_default_source ()

    ESource *           e_source_list_peek_default_source   (ESourceList *list);

Attempts to find a default ESource in `source_list` by looking for a source with a property named "default", or else a source with a property named "system". If no such ESource exists, the function returns `NULL`.

Returns : | the default ESource in `source_list`, or `NULL`. [transfer none]

Since 2.32

### e_source_list_add_group ()

    gboolean            e_source_list_add_group             (ESourceList *list,
                                                             ESourceGroup *group,
                                                             gint position);

### e_source_list_remove_group ()

    gboolean            e_source_list_remove_group          (ESourceList *list,
                                                             ESourceGroup *group);

Removes the first ESourceGroup with a unique ID matching `group` (possibly `group` itself) from `list`. The function returns `TRUE` if a matching group was found, otherwise `FALSE`.

`list` : | an ESourceList
`group` : | an ESourceGroup
Returns : | `TRUE` if an ESourceGroup was removed, `FALSE` otherwise

### e_source_list_remove_group_by_uid ()

    gboolean            e_source_list_remove_group_by_uid   (ESourceList *list,
                                                             const gchar *uid);

Removes the first ESourceGroup with the given unique ID from `list`. The function returns `TRUE` if a matching group was found, otherwise `FALSE`.

`list` : | an ESourceList
`uid` : | the unique ID of an ESourceGroup
Returns : | `TRUE` if an ESourceGroup was removed, `FALSE` otherwise

### e_source_list_ensure_group ()

    ESourceGroup *      e_source_list_ensure_group          (ESourceList *list,
                                                             const gchar *name,
                                                             const gchar *base_uri,
                                                             gboolean ret_it);

Ensures an ESourceGroup with the given base URI exists in `list`, and renames its to the given name. If `ret_it` is `TRUE`, the matching group will be returned and should be unreferenced with `g_object_unref()`.

`list` : | an ESourceList
`name` : | a localized group name
`base_uri` : | a group base URI
`ret_it` : | whether to return the group
Returns : | the matching ESourceGroup if `ret_it` is `TRUE`, otherwise `NULL`. [transfer full]

Since 2.28

### e_source_list_remove_group_by_base_uri ()

    gboolean            e_source_list_remove_group_by_base_uri
                                                            (ESourceList *list,
                                                             const gchar *base_uri);

Removes the first ESourceGroup having the given base URI from `list`. The base URI is usually just the URI scheme, such as "http://". The function returns `TRUE` if a matching group was found, otherwise `FALSE`.

`list` : | an ESourceList
`base_uri` : | a group base URI
Returns : | `TRUE` if an ESourceGroup was removed, `FALSE` otherwise

Since 2.28

### e_source_list_remove_source_by_uid ()

    gboolean            e_source_list_remove_source_by_uid  (ESourceList *list,
                                                             const gchar *uidj);

Removes the first ESource with the given unique ID from `list`. The function returns `TRUE` if a matching source was found, otherwise `FALSE`.

`list` : | an ESourceList
Returns : | `TRUE` if an ESource was removed, `FALSE` otherwise

### e_source_list_sync ()

    gboolean            e_source_list_sync                  (ESourceList *list,
                                                             GError **error);

Writes the contents of `list` to GConf. If an error occurs, such as the GConf daemon not responding, the function sets `error` and returns `FALSE`.

`list` : | an ESourceList
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### e_source_list_is_gconf_updated ()

    gboolean            e_source_list_is_gconf_updated      (ESourceList *list);

Returns `TRUE` if the GConf data for `list` is up-to-date, `FALSE` if `e_source_list_sync()` should be called.

`list` : | an ESourceList
Returns : | `TRUE` if the GConf data for `list` is up-to-date

## Signal Details

### The `"changed"` signal

    void                user_function                      (ESourceList *esourcelist,
                                                            gpointer     user_data)        : Run Last

`esourcelist` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"group-added"` signal

    void                user_function                      (ESourceList  *esourcelist,
                                                            ESourceGroup *arg1,
                                                            gpointer      user_data)        : Run Last

`esourcelist` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"group-removed"` signal

    void                user_function                      (ESourceList  *esourcelist,
                                                            ESourceGroup *arg1,
                                                            gpointer      user_data)        : Run Last

`esourcelist` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.