Synchronization

About the actual synchronization process

Synchronization logic

These steps are performed when synchronizing a collection:

  1. Prepare synchronization: prepare local collection, settings etc.
  2. Query capabilities: for instance, determine whether the server supports VCard 4
  3. Process locally deleted resources: if a local resource is flagged as deleted,
    • delete it on the server (HTTP DELETE with If-Match set to last known ETag to avoid deleting resources which have been changed on the server in the meanwhile) and
    • then remove it locally
  4. Prepare local dirty resources: assign a random UID and resource name to new resources; various contact group and recurring event operations
  5. Upload dirty resources:
    • If no previous ETag of the resource is known (i.e. the resource has not been uploaded yet), use HTTP PUT with If-None-Match: * to avoid overwriting a possibly existing resource with the same name
    • If a previous ETag of the resource is known, use HTTP PUT with If-Match set to last known ETag to avoid overwriting changes which happend on the server in the meanwhile
    • remember returned ETag as last known ETag; otherwise reset last known ETag
  6. Check CTag (sync state) of the collection
    • abort sync if CTag was returned and hasn't changed since last sync
  7. List local resources (only names and last known ETag)
  8. List remote resources (only names and ETags)
    • contacts, tasks: HTTP PROPFIND
    • events: HTTP REPORT calendar-query with time-range filter
  9. Compare local and remote resources:
    • locally delete resources which are not present on the server anymore
    • determine remote resources which are not present locally (→ have been created on the server since last sync) or
    • whose ETag has changed (→ have been modified on the server since last sync)
  10. Download remote resources: download remote resources
    • in bunches of max. 10 contacts at once using HTTP REPORT addressbook-multiget or
    • in bunches of max. 20 events/tasks at once using HTTP REPORT calendar-multiget and
    • insert them into the respective local storage
  11. Post-processing: clean up empty contact groups etc.
  12. Save sync state (CTag)

Conflict handling

Conflicts occur when different versions of a resource are available and it's ambigous which one shall be used. For instance:

  1. A contact exists on the server and has been synchronized to a mobile phone with DAVdroid and to a desktop PC with Gnome Evolution.
  2. You modify the contact with Evolution, which immediately uploads it to the server.
  3. You modify the same contact on your mobile device, too.
  4. DAVdroid wants to upload the modified contact and finds that it has been changed on the server in the meanwhile. Now there's a conflict of two different versions of this contact.

How DAVdroid handles such conflicts:

  • DAVdroid relies on HTTP ETags to determine whether a resource has been changed on the server.
  • The server always wins. If a local resource can't be uploaded or deleted safely because it has been modified on the server in the meanwhile, local changes are discarded and the server version is used.
  • DAVdroid doesn't involve the user in resolving conflicts (like asking which version shall be used) because it's supposed to run in the background silently.

Error handling

DAVdroid uses two facilities to report synchronization errors:

  1. DAVdroid can report success or error states back to the Android sync framework that calls DAVdroid. In this case, Android settings / Accounts will shown the DAVdroid account as "currently experiencing problems" (see screenshot).
  2. DAVdroid can show Android notifications with an error message. You can open those notifications to get debug information that can be shared over email.

In case of soft errors like I/O errors, DAVdroid doesn't show a notification but reports the status back to the Android sync framework. For instance, you won't get a notification just because your network connection was lost during a synchronization.

In some cases, errors may be considered to be soft errors although they're (semi-)permanent, for instance when your server is not reachable because its DNS entry has been removed. In such cases, DAVdroid won't show a notification, so you should verify that DAVdroid is really synchronizing your data from time to time.

When an error has occured, DAVdroid does not continue synchronization of the respective account / content provider to avoid data loss and inconsistent synchronization states.

Last updated: 06 Feb 2018