6b09f2f6c3
implemented the new begin/endSync() callbacks explain the change tracking and error handling -> copying from server works, the other way around fails, probably because of vcard 3.0 parsing problems on the server git-svn-id: https://zeitsenke.de/svn/SyncEvolution/trunk@6 15ad00c4-1369-45f4-8270-35d70d36bdcd
185 lines
6.8 KiB
Plaintext
185 lines
6.8 KiB
Plaintext
Introduction
|
|
------------
|
|
|
|
sync4jevolution synchronizes Evolution's contact and calender items
|
|
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.
|
|
|
|
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 drive 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.
|
|
|
|
The server configuration file should contain the following entries:
|
|
# the base URL of the SyncML server
|
|
syncURL = http://localhost:8080/sync4j/sync
|
|
|
|
# the SyncML gets this string and will use it to keep track
|
|
# of changes that still need to be synchronized; when multiple
|
|
# users access the server, this should be set to something unique
|
|
deviceId = sc-api-nat
|
|
|
|
# authorization for the SyncML server
|
|
username = guest
|
|
password = guest
|
|
|
|
# ???
|
|
firstTimeSyncMode = 0
|
|
|
|
# set to T to enable an HTTP proxy
|
|
useProxy = F
|
|
# proxy URL (http://<host>:<port>)
|
|
proxyHost =
|
|
|
|
# used by the SyncML library internally; do not modify
|
|
begin =
|
|
end =
|
|
|
|
# obsolete?
|
|
serverName =
|
|
|
|
|
|
Each data source is configured in
|
|
$HOME/.sync4j/evolution/<server>/sources/<source>/config.txt
|
|
|
|
Here is a file which would be used to synchronize the default
|
|
Evolution contacts with the Sync4j server:
|
|
|
|
# name of the source
|
|
name = card
|
|
|
|
# set to T if this source is not to be synchronized
|
|
disabled =
|
|
|
|
# requests a certain synchronization mode:
|
|
# refresh = only exchange modified items if possible
|
|
# slow = exchange all items
|
|
# two-way-one-way = ???
|
|
sync = refresh
|
|
|
|
# overrides the supported synchronization modes
|
|
syncModes = slow,two-way-one-way,refresh
|
|
|
|
# specifies the format of the data
|
|
# text/x-vcalendar = Evolution calender data
|
|
# text/x-vcard = Evolution contact data
|
|
type = text/x-vcard
|
|
|
|
# picks one of Evolution's data sources:
|
|
# enter either the name or the full URL
|
|
evolutionsource =
|
|
|
|
# this is appended to the server's URL to identify the
|
|
# server's database
|
|
uri = briefcase
|
|
|
|
# authentication for Evolution source
|
|
evolutionuser =
|
|
evolutionpassword =
|
|
|
|
# used by the SyncML library internally; do not modify
|
|
last = 1128964758
|
|
|
|
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. The Evolution data source is
|
|
determined by the type of data given in "type" and uniquely identified
|
|
with the "evolutionurl" property. Not giving an url implies that
|
|
Evolution's default contact or calender is to be used.
|
|
|
|
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.
|
|
|
|
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. Also needed are the Evolution
|
|
development files. The code was tested with Evolution
|
|
2.0.4 and 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.
|