[Opensync-devel] How evo capabilities work (was Re: capabilities problem)

[Chris F. <cd...@fo...>]

On Fri, Aug 02, 2013 at 02:43:46PM +0100, Mark Ellis wrote:
> After some thinking, should evo sync even have a format ? We get vformat
> from evo, the vformat plugin even has some extensions for evolution, and
> I don't think the evolution format plugin will actually get used, it
> probably just gets loaded because it exists ?

Oy, it took me a while to find this, so I'll try to document my
understanding. :-)

I'll use evo2_sync, as that's what I have open right now.

The evo2 sync plugin starts up, and registers its evo2_discover() function.
This discover function is then called by the library, which creates
a capability set called "evo2-caps".  It then discovers capabilities
for ebook and ecal.  These capabilities tell opensync what fields
that the evo2 sync supports.

Discovering ebook capabilities is done in evo2_ebook_discover(),
which contacts evolution and asks for the fields it supports.
It then calls evo2_capabilities_translate_ebook(), which basically
adds an objtype "contact" to the "evo2-caps", and adds all the
fieldnames returned by evolution to that objtype capability list.

We now have "evo2-caps" which supports "contact" objtypes, and a
list of names specific to evolution that represent
what contact fields it supports.  We know this because evo2_discover()
calls osync_plugin_info_set_capabilities(), setting this new
"evo2-caps" as this plugin's capability set.

But all this is useless, because while the engine knows that
the evo2_sync plugin can handle contact objtypes, it also knows
that it must serve the data to the plugin in vcard30 format,
without using any fields that the plugin doesn't support.
Unfortunately, the library engine has no idea what the
capability names in "evo2-caps" mean, as they are evolution
names and not related to any format that opensync understands.

But it does know what the names are for XMLFormat, and what those
fields mean.

This is where the evo2 format plugin steps in, which provides only
the conversion aspect of a format plugin, not the format part.

The evo2 format plugin registers a caps_converter which points
to "evo2-caps" and "xmlformat".  This caps converter takes the
capabilities of the plugin ("evo2-caps"), and creates a new capabilities
set ("xmlformat", see evolution2_format.c:caps_conv_evo2_to_xmlformat()),
with its "contact" objtype filled in with xmlformat names,
matching the xmlformat schema.

Now the engine has all the information it needs.  It knows the sync
plugin's objtype (contact), its format (vcard30), its capabilities
(evo2-caps, for objtype contact), and how to put meaning to those
capabilities (the caps converter to xmlformat).  It can now take data from
some other plugin, convert that to xmlformat, strip out any fields
that evolution can't handle, then convert it to vcard30, and vice versa,
all while being completely automatic.  There are no config files for
evolution... this data comes straight from evolution itself, and so
if evolution changes, the plugin adapts as well.

So short answer: yes, as I see it, we do need the evo2 format plugin. :-)

- Chris