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


Service: org._01.pim.contacts
Interface: org._01.pim.contacts.Manager
Object path: /org/01/pim/contacts

...

Signals:

    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
         as value.

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
each phase.