Currently the user of the PIM API only gets a single "success/failure" boolean back from the SyncPeer call. It is desirable to get more information, for example to determine whether a copy of the local data needs to be refreshed.
It is hard to determine in the implementation what has changed (text, photos, or both). This might have to be added later, so the proposed API change should allow conveying that information without another API change.
Only changing the return code of SyncPeer is not enough. The "incremental PHOTO download" issue (bug #59551) suggests to do the initial sync (and just the initial sync!) in two phases: first just the text, then with photos.
The problem with the SyncPeer API is that the method will only return after
the second phase. There is no way to notify the caller that the first
phase is over and that running a search will now produce results. This
defeats the purpose of the incremental photo download.
So here's the proposed API change and a new signal for the incremental case:
dict SyncPeer(string uid)
Retrieve contacts from the peer and ensure that the local
cache is identical to the address book of the peer. The call
returns once the operation is complete.
Only if there was no error can the caller assume that the cache
is up-to-date. In this case, a string to variant dictionary
is returned which provided additional information about the sync.
If the call fails, no dictionary is returned and the local
cache may or may not be up-to-date.
SyncEvolution will return a dict with the following entries:
"modified": boolean - data was modified
"added" : integer - number of new contacts
"modified" : integer - number of updated contacts
"removed" : integer - number of deleted contacts
Object path: /org/01/pim/contacts
void SyncProgress(string uid, string event, dict data)
Provides information about a running sync for the peer with
the given "uid". The "event" string describes what happened
and the "data" dictionary provides further information about
it with a mapping from event specific string keys to variants
The data dict has the same keys as for SyncPeer.
For SyncEvolution, I could emit (in this order):
started modified* done
Note that "modified" may occur zero or more times. In the upcoming
implementation, it would get emitted at most two times, at the end of
In master, see
Author: Patrick Ohly <firstname.lastname@example.org>
Date: Tue May 7 16:39:50 2013 +0200
PIM: new return value for SyncPeer(), new SyncProgress signal (FDO #63417)
The SyncPeer() result is derived from the sync statistics. To have
them available, the "sync done" signal must include the SyncReport.
Start and end of a sync could already be detected; "modified" signals
while a sync runs depends on a new signal inside the SyncContext when
switching from one cycle to the next and at the end of the last one.