This page documents tips for porting Evolution-Data-Server client applications from the old GConf-based ESource API to the new key-file-based ESource API.

What Changed

For many years Evolution-Data-Server has tracked account information by essentially stuffing XML configuration files into GConf keys, making it difficult for users to back up their account information or copy it to another machine. Evolution-Data-Server also had a completely separate API for email accounts even though they too were tracked as XML configuration files stuffed into a GConf key. The Evolution developers have long wanted to unify all account information under a single API, using a nicer data format that lives outside of a settings database.

The new key-file based ESource API solves both problems by storing all account information as plain text files located in $HOME/.config/evolution/sources and using a more readable and extensible file format that can be parsed by GLib's GKeyFile API.

In addition, Evolution-Data-Server introduces a new D-Bus service named evolution-source-registry which serves these key files to client applications and performs various other account-related tasks such as cleaning up old abandoned cache directories, monitoring the GNOME Online Accounts service, and centralizing password prompting and keyring management.

An overview of the new file format and the conventions associated with it are at ../ESourceFileFormat. It's recommended to at least skim through the file format overview before proceeding.

API documentation for ESource, ESourceRegistry and the various extension classes are at http://developer.gnome.org/libedataserver/stable/.

What happened to ESourceList and EAccountList?

ESourceList (for calendars and address books) and EAccountList (for mail accounts) have been replaced by a new class named ESourceRegistry, which acts as a proxy for the evolution-source-registry D-Bus service. This class is meant to be a singleton instance in each client application. An ESourceRegistry contains a hierachy of ESource instances describing all available Evolution-Data-Server accounts in one place.

What happened to ESourceGroup?

All ESource instances now share the same UID namespace and logically form a single hierarchy by way of their parent property. The parent property names the UID of a "parent" ESource, or it can be NULL to signify a "top-level" ESource.

Evolution-Data-Server ships a number of key files which act as top-level placeholders in the ESource hierarchy, mostly for display purposes. These top-level placeholders are an approximate replacement for ESourceGroup and have special well-known UIDs such as "caldav-stub" or "ldap-stub" so that CalDAV calendars and LDAP address books can easily name these UIDs in their parent property.

What happened to relative and absolute ESource URIs?

Evolution-Data-Server no longer uses the URIs of external resources to try and identify its own internal resources, as these URIs proved to be neither unique nor stable ESource identifiers. An ESource instance is now identified exclusively by its unique (and stable) identifier or UID string, accessible via e_source_get_uid().

UID strings tend to look like gibberish, such as "1166214242.20588.0@domainname". They have no inherent meaning other than being unique and stable.

Look up an ESource by its UID string like so:

source = e_source_registry_ref_source (registry, uid_string);

The returned ESource is referenced, so remember to call g_object_unref() when finished with it.

What happened to EClient's "authenticate" signal?

Client applications are freed from the burden of participating in Evolution-Data-Server backend authentication. The evolution-source-registry D-Bus service centralizes keyring lookups and password prompting, and calendar and address book backends now speak directly to it when authentication is required. A system modal password dialog will be automatically shown to the user as needed.

What replaces e_book_client_get_sources() and e_book_get_addressbooks()?

Under the new file format, a key file describes an address book if it contains an [Address Book] key file group. The [Address Book] key file group maps to the ESourceAddressBook extension class.

Obtain a list of ESource instances containing an ESourceAddressBook extension and free the list when finished like so:

GList *list;

list = e_source_registry_list_sources (registry, E_SOURCE_EXTENSION_ADDRESS_BOOK);

...

g_list_free_full (list, g_object_unref);

What replaces e_cal_client_get_sources() and e_cal_get_sources()?

Under the new file format, a key file describes a calendar if it contains a [Calendar] key file group. The [Calendar] key file group maps to the ESourceCalendar extension class.

Obtain a list of ESource instances containing an ESourceCalendar extension and free the list when finished like so:

GList *list;

list = e_source_registry_list_sources (registry, E_SOURCE_EXTENSION_CALENDAR);

...

g_list_free_full (list, g_object_unref);

Similarly for memo lists and task lists, the extension names to pass to e_source_registry_list_sources() are E_SOURCE_EXTENSION_MEMO_LIST and E_SOURCE_EXTENSION_TASK_LIST.

Where do I get an ESourceRegistry from?

The ESourceRegistry is meant to be a singleton instance, globally available within an application. It should be created first thing on startup, using either e_source_registry_new to create it asynchronously or e_source_registry_new_sync to create it synchronously. As part of its instantiation, the ESourceRegistry will connect to the evolution-source-registry service and load all available ESource instances.

In Evolution, the EShell (itself a singleton instance) holds the ESourceRegistry. Access it like so:

shell = e_shell_get_default ();
registry = e_shell_get_registry (shell);

It's preferred to keep e_shell_get_default calls to a minimum, so obtain the EShell by other means if possible.

How do I obtain a "system" or built-in ESource?

Evolution-Data-Server provides a built-in address book, calendar, memo list and task list, all of which use the local storage backend. These usually have a display name of "Personal" and have traditionally had a relative URI of "system". Hence the term "system" ESource.

In the past, Evolution set these "system" sources up by inserting pre-defined XML configuration files into the appropriate GConf keys on startup. Other client applications had to either copy this logic out of Evolution and execute it themselves, or depend on Evolution being run once to set things up properly. These "system" sources are now pre-defined, translated key files which are shipped with Evolution-Data-Server and installed in and read from a special system-wide directory. Evolution is no longer required.

The new ESourceRegistry class provides functions for accessing these built-in sources. They are as follows:

source = e_source_registry_ref_builtin_address_book (registry);

source = e_source_registry_ref_builtin_calendar (registry);

source = e_source_registry_ref_builtin_memo_list (registry);

source = e_source_registry_ref_builtin_task_list (registry);

If Evolution-Data-Server is installed properly, these functions will never return NULL and can serve as reliable fallbacks.

For each of these functions the returned ESource is referenced, so remember to call g_object_unref() when finished with it.

How do I create a new calendar or address book?

The basic steps to create a new standalone calendar or address book are:

1. Create a new scratch ESource with e_source_new (NULL, NULL, NULL).

• A scratch ESource has no GDBusObject and is useful only for initial configuration. Think of it as an unofficial draft of an ESource scribbled on a scratch piece of paper.

2. Configure the scratch ESource according to ../ESourceFileFormat.

• Make sure to give it a valid calendar or address book backend name and corresponding parent UID. For example, the backend name for a local calendar or address book is "local" and the parent UID should be "local-stub".

3. Submit the scratch ESource to the ESourceRegistry with e_source_registry_commit_source().

• If the registry service accepts the data, all running Evolution-Data-Server clients will be notified of the new data source and the ESourceRegistry will create an equivalent ESource with a GDBusObject (i.e. an official copy of the scratch ESource).

4. Note the UID of the scratch ESource and obtain the official ESource by passing the same UID to e_source_registry_ref_source().

• Use the official ESource to create an ECalClient or EBookClient instance, from which you can issue calendar or address book commands. Don't forget to call g_object_unref() on the returned ESource.

5. Discard the scratch ESource with g_object_unref().