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.

1 files changed, 23 insertions, 0 deletions

diff --git a/src/dbus/server/pim/README b/src/dbus/server/pim/README
index 97d53a39..e351e0a8 100644
--- a/src/dbus/server/pim/README
+++ b/src/dbus/server/pim/README
@@ -247,6 +247,29 @@ Not supported via the API at the moment:
 - selecting a specific phone address book
 - selecting which vCard properties get cached
 
+Syncing
+=======
+
+SetSync() in SyncEvolution will return a dict with all of the
+following entries set:
+    "modified": boolean - data was modified
+    "added" : integer - number of new contacts
+    "updated" : integer - number of updated contacts
+    "removed" : integer - number of deleted contacts
+
+In other words, the caller can reliably detect when nothing changed,
+but when contacts were modified or added, it needs to read them to
+determine which kind of properties were modified or added.
+
+The SyncProgress is triggered by SyncEvolution with three different
+keys (in this order, with "modified" occuring zero or more times):
+  "started" "modified"* "done"
+
+"started" and "done" send an empty data dictionary. "modified" sends
+the same dictionary as the one returned by SyncPeer(), if contact data
+was modified. So by definition, "modified" will be True in the
+dictionary, but is included anyway for the sake of consistency.
+
 
 Contact Data
 ============