ESourceRegistry

## ESourceRegistry ESourceRegistry — A central repository for data sources |

## Synopsis

    #include <libedataserver/libedataserver.h>

    struct              ESourceRegistry;
    ESourceRegistry *   e_source_registry_new_sync          (GCancellable *cancellable,
                                                             GError **error);
    void                e_source_registry_new               (GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    ESourceRegistry *   e_source_registry_new_finish        (GAsyncResult *result,
                                                             GError **error);
    gboolean            e_source_registry_authenticate_sync (ESourceRegistry *registry,
                                                             ESource *source,
                                                             ESourceAuthenticator *auth,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_source_registry_authenticate      (ESourceRegistry *registry,
                                                             ESource *source,
                                                             ESourceAuthenticator *auth,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_source_registry_authenticate_finish
                                                            (ESourceRegistry *registry,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_source_registry_commit_source_sync
                                                            (ESourceRegistry *registry,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_source_registry_commit_source     (ESourceRegistry *registry,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_source_registry_commit_source_finish
                                                            (ESourceRegistry *registry,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_source_registry_create_sources_sync
                                                            (ESourceRegistry *registry,
                                                             GList *list_of_sources,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_source_registry_create_sources    (ESourceRegistry *registry,
                                                             GList *list_of_sources,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_source_registry_create_sources_finish
                                                            (ESourceRegistry *registry,
                                                             GAsyncResult *result,
                                                             GError **error);
    ESource *           e_source_registry_ref_source        (ESourceRegistry *registry,
                                                             const gchar *uid);
    GList *             e_source_registry_list_sources      (ESourceRegistry *registry,
                                                             const gchar *extension_name);
    GList *             e_source_registry_list_enabled      (ESourceRegistry *registry,
                                                             const gchar *extension_name);
    ESource *           e_source_registry_find_extension    (ESourceRegistry *registry,
                                                             ESource *source,
                                                             const gchar *extension_name);
    gboolean            e_source_registry_check_enabled     (ESourceRegistry *registry,
                                                             ESource *source);
    GNode *             e_source_registry_build_display_tree
                                                            (ESourceRegistry *registry,
                                                             const gchar *extension_name);
    void                e_source_registry_free_display_tree (GNode *display_tree);
    gchar *             e_source_registry_dup_unique_display_name
                                                            (ESourceRegistry *registry,
                                                             ESource *source,
                                                             const gchar *extension_name);
    void                e_source_registry_debug_dump        (ESourceRegistry *registry,
                                                             const gchar *extension_name);
    ESource *           e_source_registry_ref_builtin_address_book
                                                            (ESourceRegistry *registry);
    ESource *           e_source_registry_ref_default_address_book
                                                            (ESourceRegistry *registry);
    void                e_source_registry_set_default_address_book
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);
    ESource *           e_source_registry_ref_builtin_calendar
                                                            (ESourceRegistry *registry);
    ESource *           e_source_registry_ref_default_calendar
                                                            (ESourceRegistry *registry);
    void                e_source_registry_set_default_calendar
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);
    ESource *           e_source_registry_ref_builtin_mail_account
                                                            (ESourceRegistry *registry);
    ESource *           e_source_registry_ref_default_mail_account
                                                            (ESourceRegistry *registry);
    void                e_source_registry_set_default_mail_account
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);
    ESource *           e_source_registry_ref_default_mail_identity
                                                            (ESourceRegistry *registry);
    void                e_source_registry_set_default_mail_identity
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);
    ESource *           e_source_registry_ref_builtin_memo_list
                                                            (ESourceRegistry *registry);
    ESource *           e_source_registry_ref_default_memo_list
                                                            (ESourceRegistry *registry);
    void                e_source_registry_set_default_memo_list
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);
    ESource *           e_source_registry_ref_builtin_task_list
                                                            (ESourceRegistry *registry);
    ESource *           e_source_registry_ref_default_task_list
                                                            (ESourceRegistry *registry);
    void                e_source_registry_set_default_task_list
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);
    ESource *           e_source_registry_ref_default_for_extension_name
                                                            (ESourceRegistry *registry,
                                                             const gchar *extension_name);
    void                e_source_registry_set_default_for_extension_name
                                                            (ESourceRegistry *registry,
                                                             const gchar *extension_name,
                                                             ESource *default_source);

## Object Hierarchy

      GObject
       +----ESourceRegistry

## Implemented Interfaces

ESourceRegistry implements GInitable and GAsyncInitable.

## Properties

      "default-address-book"     ESource*              : Read / Write
      "default-calendar"         ESource*              : Read / Write
      "default-mail-account"     ESource*              : Read / Write
      "default-mail-identity"    ESource*              : Read / Write
      "default-memo-list"        ESource*              : Read / Write
      "default-task-list"        ESource*              : Read / Write

## Signals

      "source-added"                                   : Run Last
      "source-changed"                                 : Run Last
      "source-disabled"                                : Run Last
      "source-enabled"                                 : Run Last
      "source-removed"                                 : Run Last

## Description

The ESourceRegistry is a global singleton store for all ESource instances. It uses file monitors to react to key file creation and deletion events, either constructing an ESource instance from the newly created key file, or removing from the logical ESource hierarchy the instance corresponding to the deleted key file.

The ESourceRegistry can be queried for individual ESource instances by their unique identifier string or key file path, for collections of ESource instances having a particular extension, or for all available ESource instances.

The ESourceRegistry API also provides a front-end for the "org.gnome.Evolution.DefaultSources" GSettings schema which tracks which ESource instances are designated to be the user's default address book, calendar, memo list and task list for desktop integration.

## Details

### struct ESourceRegistry

    struct ESourceRegistry;

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

Since 3.6

### e_source_registry_new_sync ()

    ESourceRegistry *   e_source_registry_new_sync          (GCancellable *cancellable,
                                                             GError **error);

Creates a new ESourceRegistry front-end for the registry D-Bus service. If an error occurs in connecting to the D-Bus service, the function sets `error` and returns `NULL`.

`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | a new ESourceRegistry, or `NULL`

Since 3.6

### e_source_registry_new ()

    void                e_source_registry_new               (GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously creates a new ESourceRegistry front-end for the registry D-Bus service.

When the operation is finished, `callback` will be called. You can then call `e_source_registry_new_finish()` to get the result of the operation.

`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

Since 3.6

### e_source_registry_new_finish ()

    ESourceRegistry *   e_source_registry_new_finish        (GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_source_registry_new_finish()`. If an error occurs in connecting to the D-Bus service, the function sets `error` and returns `NULL`.

`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | a new ESourceRegistry, or `NULL`

Since 3.6

### e_source_registry_authenticate_sync ()

    gboolean            e_source_registry_authenticate_sync (ESourceRegistry *registry,
                                                             ESource *source,
                                                             ESourceAuthenticator *auth,
                                                             GCancellable *cancellable,
                                                             GError **error);

Authenticates `source`, using `auth` to handle the authentication attempts. The operation loops until authentication is successful or the user aborts further authentication attempts. If an error occurs, the function will set `error` and return `FALSE`.

Note that `source` need not have a GDBusObject, which means this function can test authentication on a scratch ESource.

Only backend implementations and data source editors should call this function. The intent is for basic client applications to not have to deal with authentication at all.

`registry` : | an ESourceRegistry
`source` : | an ESource
`auth` : | an ESourceAuthenticator
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

### e_source_registry_authenticate ()

    void                e_source_registry_authenticate      (ESourceRegistry *registry,
                                                             ESource *source,
                                                             ESourceAuthenticator *auth,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously authenticates `source`, using `auth` to handle the authentication attempts. The operation loops until authentication is successful or the user aborts further authentication attempts.

Note that `source` need not have a GDBusObject, which means this function can test authentication on a scratch ESource.

When the operation is finished, `callback` will be called. You can then call `e_source_registry_authenticate_finish()` to get the result of the operation.

Only backend implementations and data source editors should call this function. The intent is for basic client applications to not have to deal with authentication at all.

`registry` : | an ESourceRegistry
`source` : | an ESource
`auth` : | an ESourceAuthenticator
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

Since 3.6

### e_source_registry_authenticate_finish ()

    gboolean            e_source_registry_authenticate_finish
                                                            (ESourceRegistry *registry,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_source_registry_authenticate()`. If an error occurred, the function will set `error` and return `FALSE`.

`registry` : | an ESourceRegistry
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

### e_source_registry_commit_source_sync ()

    gboolean            e_source_registry_commit_source_sync
                                                            (ESourceRegistry *registry,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);

This is a convenience function intended for use with graphical ESource editors. Call this function when the user is finished making changes to `source`.

If `source` has a GDBusObject, its contents are submitted to the D-Bus service through `e_source_write_sync()`.

If `source` does NOT have a GDBusObject (implying it's a scratch ESource), its contents are submitted to the D-Bus service through either `e_source_remote_create_sync()` if `source` is to be a collection member, or `e_source_registry_create_sources_sync()` if `source` to be an independent data source.

If an error occurs, the function will set `error` and return `FALSE`.

`registry` : | an ESourceRegistry
`source` : | an ESource with changes to commit
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

### e_source_registry_commit_source ()

    void                e_source_registry_commit_source     (ESourceRegistry *registry,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

See `e_source_registry_commit_source_sync()` for details.

When the operation is finished, `callback` will be called. You can then call `e_source_registry_commit_source_finish()` to get the result of the operation.

`registry` : | an ESourceRegistry
`source` : | an ESource with changes to commit
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

Since 3.6

### e_source_registry_commit_source_finish ()

    gboolean            e_source_registry_commit_source_finish
                                                            (ESourceRegistry *registry,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_source_registry_commit_source()`.

If an error occurred, the function will set `error` and return `FALSE`.

`registry` : | an ESourceRegistry
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

### e_source_registry_create_sources_sync ()

    gboolean            e_source_registry_create_sources_sync
                                                            (ESourceRegistry *registry,
                                                             GList *list_of_sources,
                                                             GCancellable *cancellable,
                                                             GError **error);

Requests the D-Bus service create new key files for each ESource in `list_of_sources`. Each list element must be a scratch ESource with no GDBusObject.

If an error occurs, the function will set `error` and return `FALSE`.

`registry` : | an ESourceRegistry
`list_of_sources` : | a list of ESource instances with no GDBusObject. [element-type ESource]
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

### e_source_registry_create_sources ()

    void                e_source_registry_create_sources    (ESourceRegistry *registry,
                                                             GList *list_of_sources,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously requests the D-Bus service create new key files for each ESource in `list_of_sources`. Each list element must be a scratch ESource with no GDBusObject.

When the operation is finished, `callback` will be called. You can then call `e_source_registry_create_sources_finish()` to get the result of the operation.

`registry` : | an ESourceRegistry
`list_of_sources` : | a list of ESource instances with no GDBusObject. [element-type ESource]
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

Since 3.6

### e_source_registry_create_sources_finish ()

    gboolean            e_source_registry_create_sources_finish
                                                            (ESourceRegistry *registry,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_source_registry_create_sources()`.

If an error occurred, the function will set `error` and return `FALSE`.

`registry` : | an ESourceRegistry
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

### e_source_registry_ref_source ()

    ESource *           e_source_registry_ref_source        (ESourceRegistry *registry,
                                                             const gchar *uid);

Looks up an ESource in `registry` by its unique identifier string.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
`uid` : | a unique identifier string
Returns : | an ESource, or `NULL` if no match was found. [transfer full]

Since 3.6

### e_source_registry_list_sources ()

    GList *             e_source_registry_list_sources      (ESourceRegistry *registry,
                                                             const gchar *extension_name);

Returns a list of registered sources, sorted by display name. If `extension_name` is given, restrict the list to sources having that extension name.

The sources returned in the list are referenced for thread-safety. They must each be unreferenced with `g_object_unref()` when finished with them. Free the returned list itself with `g_list_free()`.

An easy way to free the list properly in one step is as follows:

    1
    g_list_free_full (list, g_object_unref);

`registry` : | an ESourceRegistry
`extension_name` : | an extension name, or `NULL`. [allow-none]
Returns : | a sorted list of sources. [element-type ESource][transfer full]

Since 3.6

### e_source_registry_list_enabled ()

    GList *             e_source_registry_list_enabled      (ESourceRegistry *registry,
                                                             const gchar *extension_name);

Similar to `e_source_registry_list_sources()`, but returns only enabled sources according to `e_source_registry_check_enabled()`.

The sources returned in the list are referenced for thread-safety. They must each be unreferenced with `g_object_unref()` when finished with them. Free the returned list itself with `g_list_free()`.

An easy way to free the list properly in one step is as follows:

    1
    g_list_free_full (list, g_object_unref);

`registry` : | an ESourceRegistry
`extension_name` : | an extension name, or `NULL`. [allow-none]
Returns : | a sorted list of sources. [element-type ESource][transfer full]

Since 3.10

### e_source_registry_find_extension ()

    ESource *           e_source_registry_find_extension    (ESourceRegistry *registry,
                                                             ESource *source,
                                                             const gchar *extension_name);

Examines `source` and its ancestors and returns the "deepest" ESource having an ESourceExtension with the given `extension_name`. If neither `source` nor any of its ancestors have such an extension, the function returns `NULL`.

This function is useful in cases when an ESourceExtension is meant to apply to both the ESource it belongs to and the ESource's descendants.

A common example is the ESourceCollection extension, where descendants of an ESource having an ESourceCollection extension are implied to be members of that collection. In that example, this function can be used to test whether `source` is a member of a collection.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

Note the function returns the ESource containing the ESourceExtension instead of the ESourceExtension itself because extension instances are not to be referenced directly (see `e_source_get_extension()`).

`registry` : | an ESourceRegistry
`source` : | an ESource
`extension_name` : | the extension name to find
Returns : | an ESource, or `NULL` if no match was found. [transfer full]

Since 3.6

### e_source_registry_check_enabled ()

    gboolean            e_source_registry_check_enabled     (ESourceRegistry *registry,
                                                             ESource *source);

Determines whether `source` is "effectively" enabled by examining its own "enabled" property as well as those of its ancestors in the ESource hierarchy. If all examined "enabled" properties are `TRUE`, then the function returns `TRUE`. If any are `FALSE`, then the function returns `FALSE`.

Use this function instead of `e_source_get_enabled()` to determine things like whether to display an ESource in a user interface or whether to act on the data set described by the ESource.

`registry` : | an ESourceRegistry
`source` : | an ESource
Returns : | whether `source` is "effectively" enabled

Since 3.8

### e_source_registry_build_display_tree ()

    GNode *             e_source_registry_build_display_tree
                                                            (ESourceRegistry *registry,
                                                             const gchar *extension_name);

Returns a single GNode tree of registered sources that can be used to populate a GtkTreeModel. (The root GNode is just an empty placeholder.)

Similar to `e_source_registry_list_sources()`, an `extension_name` can be given to restrict the tree to sources having that extension name. Parents of matched sources are included in the tree regardless of whether they have an extension named `extension_name`.

Disabled leaf nodes are automatically excluded from the GNode tree.

The sources returned in the tree are referenced for thread-safety. They must each be unreferenced with `g_object_unref()` when finished with them. Free the returned tree itself with `g_node_destroy()`. For convenience, `e_source_registry_free_display_tree()` does all that in one step.

`registry` : | an ESourceRegistry
`extension_name` : | an extension name, or `NULL`. [allow-none]
Returns : | a tree of sources, arranged for display. [element-type ESource][transfer full]

Since 3.6

### e_source_registry_free_display_tree ()

    void                e_source_registry_free_display_tree (GNode *display_tree);

Convenience function to free a GNode tree of registered sources created by `e_source_registry_build_display_tree()`.

`display_tree` : | a tree of sources, arranged for display

Since 3.6

### e_source_registry_dup_unique_display_name ()

    gchar *             e_source_registry_dup_unique_display_name
                                                            (ESourceRegistry *registry,
                                                             ESource *source,
                                                             const gchar *extension_name);

Compares `source`'s "display-name" against other sources having an ESourceExtension named `extension_name`, if given, or else against all other sources in the `registry`.

If `sources`'s "display-name" is unique among these other sources, the function will return the "display-name" verbatim. Otherwise the function will construct a string that includes the `sources`'s own "display-name" as well as those of its ancestors.

The function's return value is intended to be used in messages shown to the user to help clarify which source is being referred to. It assumes `source`'s "display-name" is at least unique among its siblings.

Free the returned string with `g_free()` when finished with it.

`registry` : | an ESourceRegistry
`source` : | an ESource
`extension_name` : | an extension name, or `NULL`. [allow-none]
Returns : | a unique display name for `source`

Since 3.8

### e_source_registry_debug_dump ()

    void                e_source_registry_debug_dump        (ESourceRegistry *registry,
                                                             const gchar *extension_name);

Handy debugging function that uses `e_source_registry_build_display_tree()` to print a tree of registered sources to standard output.

`registry` : | an ESourceRegistry
`extension_name` : | an extension name, or `NULL`. [allow-none]

Since 3.6

### e_source_registry_ref_builtin_address_book ()

    ESource *           e_source_registry_ref_builtin_address_book
                                                            (ESourceRegistry *registry);

Returns the built-in address book ESource.

This ESource is always present and makes for a safe fallback.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the built-in address book ESource. [transfer full]

Since 3.6

### e_source_registry_ref_default_address_book ()

    ESource *           e_source_registry_ref_default_address_book
                                                            (ESourceRegistry *registry);

Returns the ESource most recently passed to `e_source_registry_set_default_address_book()` either in this session or a previous session, or else falls back to the built-in address book.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the default address book ESource. [transfer full]

Since 3.6

### e_source_registry_set_default_address_book ()

    void                e_source_registry_set_default_address_book
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);

Sets `default_source` as the default address book. If `default_source` is `NULL`, the default address book is reset to the built-in address book. This setting will persist across sessions until changed.

`registry` : | an ESourceRegistry
`default_source` : | an address book ESource, or `NULL`. [allow-none]

Since 3.6

### e_source_registry_ref_builtin_calendar ()

    ESource *           e_source_registry_ref_builtin_calendar
                                                            (ESourceRegistry *registry);

Returns the built-in calendar ESource.

This ESource is always present and makes for a safe fallback.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the built-in calendar ESource. [transfer full]

Since 3.6

### e_source_registry_ref_default_calendar ()

    ESource *           e_source_registry_ref_default_calendar
                                                            (ESourceRegistry *registry);

Returns the ESource most recently passed to `e_source_registry_set_default_calendar()` either in this session or a previous session, or else falls back to the built-in calendar.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the default calendar ESource. [transfer full]

Since 3.6

### e_source_registry_set_default_calendar ()

    void                e_source_registry_set_default_calendar
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);

Sets `default_source` as the default calendar. If `default_source` is `NULL`, the default calendar is reset to the built-in calendar. This setting will persist across sessions until changed.

`registry` : | an ESourceRegistry
`default_source` : | a calendar ESource, or `NULL`. [allow-none]

Since 3.6

### e_source_registry_ref_builtin_mail_account ()

    ESource *           e_source_registry_ref_builtin_mail_account
                                                            (ESourceRegistry *registry);

Returns the built-in mail account ESource.

This ESource is always present and makes for a safe fallback.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the built-in mail account ESource. [transfer full]

Since 3.6

### e_source_registry_ref_default_mail_account ()

    ESource *           e_source_registry_ref_default_mail_account
                                                            (ESourceRegistry *registry);

Returns the ESource most recently passed to `e_source_registry_set_default_mail_account()` either in this session or a previous session, or else falls back to the built-in mail account.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the default mail account ESource. [transfer full]

Since 3.6

### e_source_registry_set_default_mail_account ()

    void                e_source_registry_set_default_mail_account
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);

Sets `default_source` as the default mail account. If `default_source` is `NULL`, the default mail account is reset to the built-in mail account. This setting will persist across sessions until changed.

`registry` : | an ESourceRegistry
`default_source` : | a mail account ESource, or `NULL`. [allow-none]

Since 3.6

### e_source_registry_ref_default_mail_identity ()

    ESource *           e_source_registry_ref_default_mail_identity
                                                            (ESourceRegistry *registry);

Returns the ESource most recently passed to `e_source_registry_set_default_mail_identity()` either in this session or a previous session, or else falls back to the mail identity named by the default mail account. If even that fails it returns any mail identity from `registry`, or `NULL` if there are none.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the default mail identity ESource, or `NULL`. [transfer full]

Since 3.6

### e_source_registry_set_default_mail_identity ()

    void                e_source_registry_set_default_mail_identity
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);

Sets `default_source` as the default mail identity. If `default_source` is `NULL`, the next request for the default mail identity will use the fallbacks described in `e_source_registry_ref_default_mail_identity()`.

`registry` : | an ESourceRegistry
`default_source` : | a mail identity ESource, or `NULL`. [allow-none]

Since 3.6

### e_source_registry_ref_builtin_memo_list ()

    ESource *           e_source_registry_ref_builtin_memo_list
                                                            (ESourceRegistry *registry);

Returns the built-in memo list ESource.

This ESource is always present and makes for a safe fallback.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the built-in memo list ESource. [transfer full]

Since 3.6

### e_source_registry_ref_default_memo_list ()

    ESource *           e_source_registry_ref_default_memo_list
                                                            (ESourceRegistry *registry);

Returns the ESource most recently passed to `e_source_registry_set_default_memo_list()` either in this session or a previous session, or else falls back to the built-in memo list.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the default memo list ESource. [transfer full]

Since 3.6

### e_source_registry_set_default_memo_list ()

    void                e_source_registry_set_default_memo_list
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);

Sets `default_source` as the default memo list. If `default_source` is `NULL`, the default memo list is reset to the built-in memo list. This setting will persist across sessions until changed.

`registry` : | an ESourceRegistry
`default_source` : | a memo list ESource, or `NULL`. [allow-none]

Since 3.6

### e_source_registry_ref_builtin_task_list ()

    ESource *           e_source_registry_ref_builtin_task_list
                                                            (ESourceRegistry *registry);

Returns the built-in task list ESource.

This ESource is always present and makes for a safe fallback.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the built-in task list ESource. [transfer full]

Since 3.6

### e_source_registry_ref_default_task_list ()

    ESource *           e_source_registry_ref_default_task_list
                                                            (ESourceRegistry *registry);

Returns the ESource most recently passed to `e_source_registry_set_default_task_list()` either in this session or a previous session, or else falls back to the built-in task list.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
Returns : | the default task list ESource. [transfer full]

Since 3.6

### e_source_registry_set_default_task_list ()

    void                e_source_registry_set_default_task_list
                                                            (ESourceRegistry *registry,
                                                             ESource *default_source);

Sets `default_source` as the default task list. If `default_source` is `NULL`, the default task list is reset to the built-in task list. This setting will persist across sessions until changed.

`registry` : | an ESourceRegistry
`default_source` : | a task list ESource, or `NULL`. [allow-none]

Since 3.6

### e_source_registry_ref_default_for_extension_name ()

    ESource *           e_source_registry_ref_default_for_extension_name
                                                            (ESourceRegistry *registry,
                                                             const gchar *extension_name);

This is a convenience function to return a default ESource based on `extension_name`. This only works with a subset of extension names.

If `extension_name` is E_SOURCE_EXTENSION_ADDRESS_BOOK, the function returns the current default mail identity, or else falls back to the mail identity named by the current default mail account.

If `extension_name` is E_SOURCE_EXTENSION_MEMO_LIST, the function returns the current default memo list, or else falls back to the built-in memo list.

If `extension_name` is E_SOURCE_EXTENSION_TASK_LIST, the function returns the current default task list, or else falls back to the built-in task list.

For all other values of `extension_name`, the function returns `NULL`.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`registry` : | an ESourceRegistry
`extension_name` : | an extension_name
Returns : | the default ESource based on `extension_name`. [transfer full]

Since 3.6

### e_source_registry_set_default_for_extension_name ()

    void                e_source_registry_set_default_for_extension_name
                                                            (ESourceRegistry *registry,
                                                             const gchar *extension_name,
                                                             ESource *default_source);

This is a convenience function to set a default ESource based on `extension_name`. This only works with a subset of extension names.

If `extension_name` is E_SOURCE_EXTENSION_ADDRESS_BOOK, the function sets `default_source` as the default address book. If `default_source` is `NULL`, the default address book is reset to the built-in address book.

If `extension_name` is E_SOURCE_EXTENSION_CALENDAR, the function sets `default_source` as the default calendar. If `default_source` is `NULL`, the default calendar is reset to the built-in calendar.

If `extension_name` is E_SOURCE_EXTENSION_MAIL_ACCOUNT, the function sets `default_source` as the default mail account. If `default_source` is `NULL`, the default mail account is reset to the built-in mail account.

If `extension_name` is E_SOURCE_EXTENSION_MAIL_IDENTITY, the function sets `default_source` as the default mail identity. If `default_source` is `NULL`, the next request for the default mail identity will return the mail identity named by the default mail account.

If `extension_name` is E_SOURCE_EXTENSION_MEMO_LIST, the function sets `default_source` as the default memo list. If `default_source` is `NULL`, the default memo list is reset to the built-in memo list.

If `extension_name` is E_SOURCE_EXTENSION_TASK_LIST, the function sets `default_source` as the default task list. If `default_source` is `NULL`, the default task list is reset to the built-in task list.

For all other values of `extension_name`, the function does nothing.

`registry` : | an ESourceRegistry
`extension_name` : | an extension name
`default_source` : | an ESource, or `NULL`. [allow-none]

Since 3.6

## Property Details

### The `"default-address-book"` property

      "default-address-book"     ESource*              : Read / Write

The default address book ESource.

### The `"default-calendar"` property

      "default-calendar"         ESource*              : Read / Write

The default calendar ESource.

### The `"default-mail-account"` property

      "default-mail-account"     ESource*              : Read / Write

The default mail account ESource.

### The `"default-mail-identity"` property

      "default-mail-identity"    ESource*              : Read / Write

The default mail identity ESource.

### The `"default-memo-list"` property

      "default-memo-list"        ESource*              : Read / Write

The default memo list ESource.

### The `"default-task-list"` property

      "default-task-list"        ESource*              : Read / Write

The default task list ESource.

## Signal Details

### The `"source-added"` signal

    void                user_function                      (ESourceRegistry *registry,
                                                            ESource         *source,
                                                            gpointer         user_data)      : Run Last

Emitted when an ESource is added to `registry`.

`registry` : | the ESourceRegistry which emitted the signal
`source` : | the newly-added ESource
`user_data` : | user data set when the signal handler was connected.

### The `"source-changed"` signal

    void                user_function                      (ESourceRegistry *registry,
                                                            ESource         *source,
                                                            gpointer         user_data)      : Run Last

Emitted when an ESource registered with `registry` emits its "changed" signal.

`registry` : | the ESourceRegistry which emitted the signal
`source` : | the ESource that changed
`user_data` : | user data set when the signal handler was connected.

### The `"source-disabled"` signal

    void                user_function                      (ESourceRegistry *registry,
                                                            ESource         *source,
                                                            gpointer         user_data)      : Run Last

Emitted when an ESource "enabled" property becomes `FALSE`.

`registry` : | the ESourceRegistry which emitted the signal
`source` : | the ESource that got disabled
`user_data` : | user data set when the signal handler was connected.

### The `"source-enabled"` signal

    void                user_function                      (ESourceRegistry *registry,
                                                            ESource         *source,
                                                            gpointer         user_data)      : Run Last

Emitted when an ESource "enabled" property becomes `TRUE`.

`registry` : | the ESourceRegistry which emitted the signal
`source` : | the ESource that got enabled
`user_data` : | user data set when the signal handler was connected.

### The `"source-removed"` signal

    void                user_function                      (ESourceRegistry *registry,
                                                            ESource         *source,
                                                            gpointer         user_data)      : Run Last

Emitted when an ESource is removed from `registry`.

`registry` : | the ESourceRegistry which emitted the signal
`source` : | the ESource that got removed
`user_data` : | user data set when the signal handler was connected.