This page documents the on-disk format of Evolution-Data-Server account files and touches on the APIs used to access account data.
API documentation for ESource, ESourceRegistry and the various extension classes are at http://developer.gnome.org/libedataserver/stable/.
Contents
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.
[Data Source] DisplayName=Google Contacts Enabled=true Parent=google-stub [Address Book] BackendName=google [Autocomplete] IncludeMe=true [Authentication] Host= Method=plain/password Port=0 User=myusername@gmail.com ProxyUid=system-proxy [Offline] StaySynchronized=false [Refresh] Enabled=true IntervalMinutes=60 [Security] Method=tls [Contacts Backend] IncludeMe=true
Calendars
A key file is treated as a calendar if it includes a [Calendar] key file group.
Other groups commonly present in a calendar key file include:
[Data Source] (required)
[Alarms] (calendars only)
[Authentication]
[Offline]
[Refresh]
[Security]
Additionally, backend-specific calendar settings reside in a special key file group named after the backend, such as [CalDAV 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 a calendar key file. The order of groups in a key file is not significant, nor is the order of keys within each group.
[Data Source] DisplayName=My Real Name Enabled=true Parent=google-stub [Calendar] BackendName=caldav Color=#a30029002900 [Authentication] Host=www.google.com Method=plain/password Port=443 User=myusername@gmail.com ProxyUid=system-proxy [Offline] StaySynchronized=false [Refresh] Enabled=true IntervalMinutes=60 [Security] Method=tls [CalDAV Backend] AvoidIfmatch=false DisplayName=My Real Name Path=/calendar/dav/myusername@gmail.com/events Autoschedule=false Email=
Memo and Task Lists
A key file is treated as a memo list if it includes a [Memo List] key file group, or as a task list if it includes a [Task List] group.
Other groups commonly present in these types of key files are identical to those in calendar key files. See above for details and an example.
Mail Account Triplets
Mail accounts are more complex than standalone address books and calenders because they're partitioned into three orthogonal key files. For the sake of discussion, we name them as follows:
1. A mail account key file describes an incoming mail server and/or a location where mail is stored.
2. A mail identity key file describes who you are and how you want your outgoing mail configured (encrypted, signed, etc.).
3. A mail transport key file describes an outgoing mail server.
The three key files are linked together by way of UID references, similar to the "Parent" key in the [Data Source] key file group discussed above.
Hierarchically, a mail account key file is typically a top-level node (no parent) with the mail identity and mail transport key files as children (both reference the mail account as their parent).
Mail Account
A key file is treated as a mail account (as defined above) if it includes a [Mail Account] key file group.
Other groups commonly present in a mail account key file include:
[Data Source] (required)
[Authentication]
[Message Disposition Notifications]
[Offline]
[Refresh]
[Security]
Additionally, backend-specific mail account settings reside in a special key file group named after the backend, such as [Imapx Backend].
The [Mail Account] key file group includes an "IdentityUid" key which specifies the UID of a mail identity key file. This serves as the default mail identity for this account.
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 a mail account key file. The order of groups in a key file is not significant, nor is the order of keys within each group.
[Data Source] DisplayName=myusername@gmail.com Enabled=true Parent= [Mail Account] IdentityUid=<<mail-identity-uid>> BackendName=imapx [Authentication] Host=imap.googlemail.com Port=993 User=myusername@gmail.com Method=none ProxyUid=system-proxy [Message Disposition Notifications] ResponsePolicy=never [Offline] StaySynchronized=false [Refresh] Enabled=false IntervalMinutes=10 [Security] Method=ssl-on-alternate-port [Imapx Backend] CheckAll=true Namespace=true FilterInbox=false BatchFetchCount=500 CheckSubscribed=false ConcurrentConnections=5 FetchOrder=ascending FilterJunk=false FilterJunkInbox=false ShellCommand=ssh -C -l %u %h exec /usr/sbin/imapd UseIdle=true UseNamespace=false UseQresync=true UseShellCommand=false UseSubscriptions=true FilterAll=false MobileMode=false
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.
[Data Source] DisplayName=myusername@gmail.com Enabled=true Parent=<<mail-account-uid>> [Mail Identity] Name=My Real Name Address=myusername@gmail.com ReplyTo= Organization= SignatureUid=<<mail-signature-uid>> [Mail Composition] DraftsFolder=folder://<<mail-account-uid>>/Drafts SignImip=true [Mail Submission] TransportUid=<<mail-transport-uid>> SentFolder=folder://<<mail-account-uid>>/Sent [Pretty Good Privacy (OpenPGP)] AlwaysSign=false AlwaysTrust=false EncryptToSelf=true [Secure MIME (S/MIME)] EncryptByDefault=false EncryptToSelf=true SignByDefault=false
Mail Transport
A key file is treated as a mail transport (as defined above) if it includes a [Mail Transport] key file group.
Other groups commonly present in a mail transport key file include:
[Data Source] (required)
[Authentication]
[Security]
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 a mail transport key file. The order of groups in a key file is not significant, nor is the order of keys within each group.
[Data Source] DisplayName=myusername@gmail.com Enabled=true Parent=<<mail-account-uid>> [Mail Transport] BackendName=smtp [Authentication] Host=smtp.googlemail.com Method=PLAIN Port=465 User=myusername@gmail.com ProxyUid=system-proxy [Security] Method=ssl-on-alternate-port
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.
[Data Source] DisplayName=Business Signature Enabled=true Parent= [Mail Signature] MimeType=text/html
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.
[Data Source] DisplayName=Company Proxy Enabled=true Parent= [Proxy] Method=manual IgnoreHosts=localhost;127.0.0.0/8;::1; AutoconfigUrl= FtpHost= FtpPort=0 HttpAuthPassword= HttpAuthUser= HttpHost=proxy.mycompany.com HttpPort=8080 HttpUseAuth= HttpsHost= HttpsPort=0 SocksHost= SocksPort=0