ESource and Key Files

The ESource class is basically just a glorified key file interface, similar to GKeyFile. ESource instances are constructed from key files which typically live in $HOME/.config/evolution/sources. The base name of the key file (minus the .source file extension) becomes the ESource's unique identity string, or "UID". ESource UID strings are usually generated by the e_uid_new() function, but really any unique name will work.

Every key file must have a group named [Data Source]. The keys in this group map directly to ESource object properties: the "DisplayName" key in the key file maps to the "display-name" ESource property, and the "Enabled" key in the key file maps to the "enabled" ESource property.

Another key in the [Data Source] group is named "Parent", which can either be blank or specify the UID of another ESource. This key works differently from the others. Instead of being merely a descriptive property, it's used to build an in-memory hierarchy of ESource objects. The "Parent" key indicates where the ESource object fits in the hierarchy. A blank "Parent" key means the ESource object is a top-level node in the hierarchy, like a folder in the root of a filesystem.

Additional groups in the key file are referred to in the ESource API as "extensions". An "extension" is really just a custom API for accessing values in a particular key file group. An "extension" also defines the data type and default value for each key in its key file group, so it acts as a kind of schema for the key file group.

All extensions share a common abstract base class named ESourceExtension. So for example, the key file group named [Calendar] is managed by a class named ESourceCalendar which is derived from ESourceExtension.

The keys in these additional key file groups map to object properties in their corresponding ESourceExtension-derived class, the same way keys in the [Data Source] group map to ESource object properties. For example, a key in the [Calendar] group named "BackendName" maps to the "backend-name" object property in the ESourceCalendar class.

Use e_source_get_extension(source, extension_name) to access an ESourceExtension from an ESource. The extension_name is also the key file group name (excluding the brackets).

Every extension class provides its extension name as a preprocessor definition. For example, the ESourceCalendar class defines this macro:

#define E_SOURCE_EXTENSION_CALENDAR "Calendar"

Using these macros rather than typing the extension names yourself helps avoid typos in your code.

Important: If the extension you're asking for in e_source_get_extension() is not already present in the ESource, the ESource will instantiate the appropriate extension class and set all of its values to pre-defined defaults. So as long as the extension_name argument is recognized, e_source_get_extension() will always work. If you just want to test for the existence of an extension in an ESource without creating it, use e_source_has_extension(source, extension_name) which just returns TRUE or FALSE.

The key file format is loosely defined in that any combination of groups in a key file is syntactically valid, but not every combination is semantically valid. Rather than build restrictions into the file format itself, Evolution-Data-Server relies on convention to know how data is organized in key files for various account types. Those conventions are documented below.

Address Books

A key file is treated as an address book if it includes an [Address Book] key file group.

Other groups commonly present in an address book key file include:

[Data Source] (required)

[Autocomplete]

[Authentication]

[Offline]

[Refresh]

[Security]

[Contacts Backend] (this refers to the "contacts" calendar backend)

Additionally, backend-specific address book settings reside in a special key file group named after the backend, such as [LDAP Backend].

The [Authentication] key file group includes a "ProxyUid" key which specifies the UID of a network proxy key file. Network proxy key files are discussed below.

Here's a complete example of an address book key file. The order of groups in a key file is not significant, nor is the order of keys within each group.

Mail Identity

A key file is treated as a mail identity (as defined above) if it includes a [Mail Identity] key file group.

Other groups commonly present in a mail identity key file include:

[Data Source] (required)

[Mail Composition]

[Mail Submission]

[Pretty Good Privacy (OpenPGP)]

[Secure MIME (S/MIME)]

The [Mail Submission] key file group includes a "TransportUid" key which specifies the UID of a mail transport key file. This serves as the default mail transport for this identity.

The [Mail Identity] key file group includes a "SignatureUid" key which specifies the UID of a mail signature key file. This serves as the default mail signature for this identity. Mail signature key files are discussed below.

Here's a complete example of a mail identity key file. The order of groups in a key file is not significant, nor is the order of keys within each group.

Mail Signatures

A key file is treated as a mail signature if it includes a [Mail Signature] key file group.

The only other group present in a mail signature key file is [Data Source], which is required in all key files.

Each mail signature key file is paired with another file of the same name in $HOME/.config/evolution/signatures. This other file is either a text/plain or text/html type file containing the actual signature content, or a symbolic link to an executable file which outputs the signature content when executed.

Here's a complete example of a mail signature key file. The order of groups in a key file is not significant, nor is the order of keys within each group.

Network Proxies

As of version 3.12, network proxy settings are also integrated into the ESource framework. With this change comes the ability to define alternate network proxy settings for particular accounts. Evolution-Data-Server includes a default network proxy key file named system-proxy.

A key file is treated as a network proxy profile if it includes a [Proxy] key file group.

Here's a complete example of a network proxy profile key file. The order of groups in a key file is not significant, nor is the order of keys within each group.