Re: [Opensync-devel] trying to understand the duplicate callback

[Daniel G. <go...@b1...>]

On Saturday, July 23, 2011 12:46:03 AM Chris Frey wrote:
> While fixing leaks, I ran across the following function in the xmlformat
> plugin:
> 
> http://repo.or.cz/w/opensync/xmlformat-cdf.git/commitdiff/d6bf4461281d96bfe
> b4bc593a087c04c6e232d3f
> 
> I've removed all the dead code (which contained a leak), but while it looks
> correct, and the sync continues to work without that dead code, it looks
> kinda odd.

Call of this duplicate is actually a quite rare event IIRC.

> 
> I just wanted to confirm:  is is true that the duplicate callback is only
> for duplicating the UID?  Why is there an output/outsize mechanism involved
> in that case?

Actually it's not only about duplicating and changing the UID to some
format specific UID format.


> 
> How else can the duplicate callback be used?


It has two more functions:

 * maybe some format specification requires that this specific format
   contains the _corect_ UID. So the data of the change can be modified
   in a format specific way to update the UID to the new generated UID.
   E.g. the file format is using that. The File format structure uses
   the path as UID. The path structure member gets updated in this function.

 * the format duplicate function can decided if this change needs to be written
   to the device or not by setting *dirty = TRUE. AFAIK if have not yet seen
   any format / sync protocol which has already some logic to avoid that a duplicated
   entry needs to be transfered.

Note: the change object/data which get passed to this function is already a duplicate.
The change got cloned by osync_change_clone() earlier and this function just allows
to make the required changes to make a 1:1 clone to a syncable "duplicated" change.
Otherwise things break if two changes with the same UID and the same format get
synced to a member/device.



The big picture or purpose of this function is this:

osync_change_duplicate() gets involved by osync_mapping_engine_duplicate() which gets called to solve a conflict. There are several ways in 
OpenSync to solve sync conflict (changes which are SIMILAR but not the SAME - e.g. on a slow-sync). You can chosse between:

 * OSYNC_ENGINE_SOLVE_CHOOSE user selects which change to pick - or preconfigured: always "winning" device

 * OSYNC_ENGINE_SOLVE_IGNORE ignore the conflict temporarily until next sync (not supported by all syncing plugins, only those which are able 
to "read" single entries which haven't changed - plugin "sync" function)

 * OSYNC_ENGINE_SOLVE_USE_LATEST use the most recent modified change (only support if the involved objformats are able to determine the last 
modification timestamp and if the timestamp of two or more entries is not equal)

 * OSYNC_ENGINE_SOLVE_DUPLICATE - this is the one in question:
   if a user modified a change (e.g. a contact entry in the addressbook) on two or more devices at the same time,
   but not resulting in a same entry (e.g. typo in the new phone number on the other device or telephone 
   number with or without country prefix. Then this solving function is the right for you if you are not sure
   which change is the correct one. This solving type is always available and safes your day if "solving by ignoring" is
   not available (because a plugin is involved which doesn't support "solving by ignoring" )




Regarding your fix. The fix looks good. Changing the content of a change is optional in the objformat duplicate() function.
Actually the entire objformat duplicate() calls is optional for most format plugins:

---8<--
/**
 * @brief Sets the duplicate function for an object format
 *
 * The duplicate function can be used to duplicate an object in your format.
 * Duplication does not mean to make two objects out of one, but to change 
 * the uid of the object in such a way that it differs from the original uid.
 *
 * Most formats will never need this.
 *
 * @param format Pointer to the object format
 * @param dupe_func The duplicate function to use
 */
OSYNC_EXPORT void osync_objformat_set_duplicate_func(OSyncObjFormat *format, OSyncFormatDuplicateFunc dupe_func);

--->8--

"Most formats will never need this." - the reason for that is that only the "most common" formats
which is used for comparing and mapping changes will only require this. So far i only have seen
xmlformat-$format and file format as the "common" format which is used to do the comparing/mapping.
Those are the only function which have "real" duplicate() function and take at least care about
changing the uid.

We might should improve this description and of OSyncFormatDuplicateFunc.

(I didn't remember all that, i had to read the calling code of the duplicate function)

Hope that helps.



Best Regards,
Daniel

-- 
Daniel Gollub
Linux Consultant & Developer
Tel.: +49-160 47 73 970 
Mail: go...@b1...

B1 Systems GmbH
Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537