git-svn-id: https://zeitsenke.de/svn/SyncEvolution/trunk@22 15ad00c4-1369-45f4-8270-35d70d36bdcd
262 lines
11 KiB
Plaintext
262 lines
11 KiB
Plaintext
Preamble
|
|
--------
|
|
|
|
This software is still experimental. Some parts of this documentation
|
|
describe how features are supposed to work although they have not been
|
|
implemented yet. They are marked with [not implemented].
|
|
|
|
|
|
Introduction
|
|
------------
|
|
|
|
sync4jevolution synchronizes Evolution's contact and calender items
|
|
[calender not implemented yet]
|
|
with a SyncML server. The items are exchanged in the vCard and
|
|
vCalender formats and via the Funambol Sync4j C++ client API library,
|
|
which should make sync4jevolution compatible with the majority of
|
|
SyncML servers. Full, one-way and incremental synchronization of items
|
|
are supported.
|
|
|
|
sync4jevolution does not synchronize with another SyncML capable
|
|
device directly: a SyncML server that that device and sync4jevolution
|
|
can talk to is needed. The remainder of this document assumes that
|
|
Funambol's Sync4j server bundle for Linux V2.3 was installed using the
|
|
default configuration.
|
|
|
|
With a server that fully supports SyncML and the vCard standard the
|
|
following works:
|
|
- copy a complete database to the server and restore it
|
|
from the server later
|
|
- delete or modify an item locally, then make the same change
|
|
on the server
|
|
- delete, modify or add items on the server (by synchronizing with
|
|
another client), then make the same change locally
|
|
- conflict resolution (where two clients modify the same item,
|
|
then sync with the server) is handled by the server, but
|
|
sync4jevolution has support which ensures that no data is lost
|
|
by creating duplicates (see Conflict Resolution below)
|
|
|
|
Although all of the features are covered by unit testing and
|
|
have been verified to work, this software is still experimental.
|
|
Make a backup of your
|
|
$HOME/.evolution/addressbook
|
|
$HOME/.evolution/calender
|
|
directories before running it for the first time. In older Evolution
|
|
versions the same data is found in $HOME/evolution.
|
|
|
|
Usage
|
|
-----
|
|
|
|
Currently sync4jevolution comes as a simple command line tool which is
|
|
configured via files. A graphical interface via an Evolution plugin
|
|
would also be possible, but is not implemented yet. As command line
|
|
parameters sync4jevolution only supports one option which specifies the
|
|
configuration file that drives the synchronization run:
|
|
|
|
sync4jevolution [<server>]
|
|
|
|
The <server> string is used to find the configuration which determines
|
|
how synchronization is going to proceed. Selection of sources of
|
|
Evolution data which are to be synchronized with that server is done
|
|
via configuration files. It is possible to configure sources without
|
|
activating their synchronization, see the "disabled" property below.
|
|
|
|
If the SyncML server is not specified, sync4jevolution lists all
|
|
available Evolution backend databases.
|
|
|
|
Progress and error messages are both sent to stdout. In case of an
|
|
error the synchronization run is aborted and sync4jevolution returns a
|
|
non-zero value. Recovery from failed synchronization is done by
|
|
forcing a full synchronization during the next run, i.e. by sending
|
|
all items and letting the SyncML server compare against the ones it
|
|
already knows.
|
|
|
|
After a successful synchronization the server's configuration file is
|
|
updated so that the next run can be done incrementally. If the
|
|
configuration file has to be recreated e.g. because it was lost, the
|
|
next run recovers from that by doing a full synchronization.
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
The configuration file of a certain <server> is stored in
|
|
$HOME/.sync4j/evolution/<server>/spds/syncml/config.txt
|
|
|
|
The format is a simple list of
|
|
<property> = <value>
|
|
pairs with one pair per line. Leading spaces and space around the
|
|
equals character are skipped. <value> then runs until the the end of
|
|
the line. In other words, it cannot start with spaces nor contain line
|
|
breaks. Do not put quotation marks around <value>, they would be
|
|
treated as part of the value itself. Lines starting with a hash (#)
|
|
after optional leading spaces are treated as comments and skipped.
|
|
|
|
Each data source is configured in
|
|
$HOME/.sync4j/evolution/<server>/spds/sources/<source>/config.txt
|
|
|
|
See "etc/example/spds/syncml/config.txt" for options in the server
|
|
configuration and "etc/example/spds/sources/addressbook_1/config.txt"
|
|
for options in the data source configuration. Without changing this
|
|
example configuration can be used for testing the operation of
|
|
sync4jevolution, see "Exchanging Data" below.
|
|
|
|
Normally at least the following configuration options need to be adapted:
|
|
spds/syncml
|
|
syncURL
|
|
deviceId
|
|
username
|
|
password
|
|
spds/sources
|
|
uri
|
|
evolutionsource
|
|
|
|
Each data source corresponds to one database at the SyncML server, so
|
|
two entries have to be added for each Evolution calendar as it stores
|
|
both events/appointments and todo items [NOT IMPLEMENTED] The Evolution data source is
|
|
determined by the type of data given in "type" and uniquely identified
|
|
with the "evolutionurl" property.
|
|
|
|
One can synchronize with multiple server databases in one run, but
|
|
the same server database can only be accessed once. To synchronize
|
|
the same server database with multiple local databases, one has
|
|
to setup two independent configurations with different "deviceId"
|
|
settings and synchronize them separately.
|
|
|
|
If the Evolution data source requires authentication, the
|
|
"evolutionuser" and "evolutionpassword" are used as credentials. In
|
|
this case the directory that contains the source's config.txt should
|
|
only be accessible by the user. [NOT IMPLEMENTED YET]
|
|
|
|
Exchanging Data
|
|
---------------
|
|
|
|
sync4jevolution transmits address book entries as vCard 2.1, although
|
|
Evolution exports them as 3.0. This is done because most servers do
|
|
not yet support importing 3.0. Importing new or modified entries from
|
|
the server can be done in 2.1 and 3.0 vCards.
|
|
|
|
How the server stores the vCards depends on its implementation and
|
|
configuration. In the default Sync4j server installation, vCards are
|
|
converted into an internal format, but it preserves the Evolution
|
|
vCard extensions.
|
|
|
|
To check which data is preserved, one can use this procedure:
|
|
1. synchronize the address book with the server
|
|
2. create an new address book in Evolution
|
|
3. add a configuration for that second address book and the
|
|
same database on the SyncML server
|
|
4. synchronize again, this time using the other data source
|
|
|
|
The "etc/localhost_1" directory contains a configuration for
|
|
a default Sync4j installation on the local host and an Evolution
|
|
address book called "sync4jevolution test #1". The
|
|
"etc/localhost_2" is the pendant for a second address book
|
|
called "sync4jevolution test #2". Both configurations can
|
|
be copied directly to ".sync4j/evolution":
|
|
mkdir -p ~/.sync4j/evolution
|
|
cp -a etc/localhost* ~/.sync4j/evolution
|
|
rm -rf ~/.sync4j/evolution/localhost*/spds/sources/CVS
|
|
The last step is only necessary when working with a checkout
|
|
of the sync4jevolution sources from CVS.
|
|
|
|
For them to work, also create the two address books
|
|
sync4jevolution test #1
|
|
sync4jevolution test #2
|
|
inside Evolution. sync4jevolution never creates address
|
|
books itself.
|
|
|
|
Steps 1 above then becomes an invocation of
|
|
sync4jevolution localhost_1
|
|
and step 4
|
|
sync4jevolution localhost_2
|
|
|
|
This copies all contacts into the server and from there into the new
|
|
address book. Now one can either compare the address books in
|
|
Evolution or do that automatically:
|
|
- save the complete address books: mark all entries, save as vCard
|
|
- normalize the files with the provided Perl script:
|
|
test/normalize_vcard.pl list1.vcf >list1.normal.vcf
|
|
test/normalize_vcard.pl list2.vcf >list2.normal.vcf
|
|
- compare the normalized lists, e.g.:
|
|
diff -c list1.normal.vcf list2.normal.vcf
|
|
|
|
Normalizing is necessary because the order of cards and their
|
|
properties as well as other minor formatting aspects may be
|
|
different. The automatic unit testing (see HACKING) also contains
|
|
a "testVCard" test which verifies the copying of contact
|
|
entries.
|
|
|
|
Modifying either address book and synchronizing back and forth
|
|
can be used to verify that sync4jevolution works as expected. If
|
|
you do not trust sync4jevolution or the server, then it is prudent
|
|
to run these checks with a copy of the original address book.
|
|
Make a backup of the .evolution/addressbook directory.
|
|
|
|
Did I mention that you should make backups?
|
|
|
|
|
|
Conflict Resolution
|
|
-------------------
|
|
|
|
If two clients make changes to the same item, the first one to
|
|
sync will get the server to copy its changes. The second one
|
|
then runs into a conflict when it tries to push its own changes
|
|
into the server.
|
|
|
|
The SyncML server now has to decide how to proceed. If the server
|
|
decides to continue with its own copy and asks to overwrite the
|
|
locally modified copy (the default with Sync4j),
|
|
sync4jevolution will make a local copy first. This leads to
|
|
duplicates which have to be merged manually on the client side
|
|
where the conflict occurred. Currently there is no support
|
|
inside sync4jevolution: there is only an ERROR entry in the
|
|
log. A summary at the end of syncing would be better, or
|
|
even opening GUI dialogs to resolve the conflicts immediately...
|
|
|
|
Tracking Changes inside Evolution
|
|
---------------------------------
|
|
|
|
The SyncML protocol requires that a client knows which items have been
|
|
added, modified and deleted since the last sync. This is supported by
|
|
the Evolution database server, albeit in a limited way:
|
|
|
|
the same function lists changes and also moves the so called "change
|
|
marker" forward. Therefore asking for changes twice in a row will only
|
|
list changes the first time and not report the same changes a second
|
|
time. sync4jevolution delays asking for changes as long as possible
|
|
and only does it when synchronization has really started. Then
|
|
if synchronization completed and items where added, modified or
|
|
deleted on behalf of the server, the change marker is moved forward.
|
|
|
|
If synchronization fails for some or all items, then sync4jevolution
|
|
cannot mark individual items for retransmission during the next
|
|
sync and forces the next sync to execute in slow mode.
|
|
|
|
The change marker that sync4jevolution uses is a string which is
|
|
composed as "sync4jevolution:<syncURL>/<name>" where <syncURL> comes
|
|
from the server config file and <name> from the source config
|
|
file. This implies that changes are tracked separately for each server
|
|
and server database that Evolution might be synchronized with.
|
|
|
|
Compiling from Source
|
|
---------------------
|
|
|
|
To compile the code the 3.x version of the Sync4j C++ client library
|
|
is needed. It is currently only available from CVS, checkout the
|
|
"3x" module from the CVS at
|
|
http://forge.objectweb.org/projects/sync4j
|
|
|
|
The recommended way to make that library available is by
|
|
installing it into its own directory (configure --prefix=<dir>; make;
|
|
make install) and then pointing the configure of sync4jevolution
|
|
towards it (configure --with-sync4j=<dir>).
|
|
|
|
Also needed are the Evolution development files. The code was tested
|
|
with Evolution 2.0.4. It is unclear which other versions it is
|
|
compatible with.
|
|
|
|
The build system is the normal autotools system.
|
|
See INSTALL for general instructions how to use that
|
|
and "./configure --help" for Sync4jEvolution specific
|
|
options.
|