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/.

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

Apps/Evolution/ESourceFileFormat (last edited 2013-10-27 14:04:01 by MatthewBarnes)