Format Plugin

[Bjoern Ricks]

Hello all,

I am trying to develop a new format plugin for tomboy notes and I am a
bit confused about what I have to implement now. Tomboy notes are stored
as XML files in a directory. At first I plan to sync them via file-sync
to another backup directory (It should be the easiest scenario). Finally
I want to sync my tomboy notes via syncml.

So my questions are:
Do I need a detector? In which case and how is the detector function
used by the opensync engine? E.g. xmlformat-doc only checks if the xml
declaration (<?xml ...?>) exists. In this case are all xml files
automatically parsed as xmlformat?
Which format should I use for osync_objformat_new ("plain","memo",
"note", ...) ?
Should I directly convert the xml tomboy notes to "xmlformat" or first
parse them to an internal struct (like xmlformat-doc) and in a next step
convert the struct to xmlformat?

Additionally the use of some functions is unclear to me.
OSyncFormatCompareFunc:
docs/example-plugin/src/format.c says: "This function can be used to
compare two types of your formats.This is optional. For example, you can
only provide a conversion from and to the xml format and let all the
comparison be done there"
How is that meant?

OpenSyncFormatDuplicateFunc and OSyncFormatCopyFunc:
What is the difference between this two function and when should I use them?

OSyncFormatRevisionFunc:
This function is a big black hole to me. It is used e.g. in xmlformat.c
but what is the intention of this function?

Best Regards

--
/Bjoern Ricks

-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Opensync-devel mailing list
Opensync-devel@...
https://lists.sourceforge.net/lists/listinfo/opensync-devel

[Daniel Gollub]

On Monday 09 June 2008 15:21:51 Bjoern Ricks wrote:
> So my questions are:
> Do I need a detector? In which case and how is the detector function
> used by the opensync engine?

Detectores are invoked by OSyncFormatEnv when calling
osync_format_env_detect_objformat_full()
osync_format_env_detect_objformat()
.. to detect the OSyncObjFormat of OSyncData. Those function never get called
by the engine itself. OpenSync API consumer use those functions - e.g.
vconvert tool which is in the vformat plugin.


The detectors get also invoked when the OpenSync engine create a conversion
path.


> E.g. xmlformat-doc only checks if the xml
> declaration (<?xml ...?>) exists. In this case are all xml files
> automatically parsed as xmlformat?

You might found a bug here. This looks like a very weak detector...


> Which format should I use for osync_objformat_new ("plain","memo",
> "note", ...) ?

"note" is actually an Object Type the rests (plain, memo, ...) are Object
Foramts. (This reminds me to create a table of ObjFormats and ObjTypes...)

osync_objformat_new("tomboy-note", "note", &error);


> Should I directly convert the xml tomboy notes to "xmlformat" or first
> parse them to an internal struct (like xmlformat-doc) and in a next step
> convert the struct to xmlformat?

I would recommend to just write two converter functions for your format
plugin:

#1 tomboy-note -> xmlformat-note
#2 xmlformat-note -> tomboy-note



> Additionally the use of some functions is unclear to me.
> OSyncFormatCompareFunc:
> docs/example-plugin/src/format.c says: "This function can be used to
> compare two types of your formats.This is optional. For example, you can
> only provide a conversion from and to the xml format and let all the
> comparison be done there"
> How is that meant?

OpenSync is able to sync all kind of formats. To sync, you need to compare
each entry with each other, to find the same or similar entries. Since
different formats are invovled we're able to avoid conversion overhead an
allow entry comparsion in different formats. For example if you sync two
instances of tomboy it would be much faster to compare each entry directly,
without converting it first to xmlformat-note and compare each entry with the
xmlformat-note.

The comment from the example plugin is really misleading - since this is
inteded for PIM format plugins. For object types  "contact", "event", "todo"
and "note" we ALWAYS convert internally first to "xmlformat-$objtype" to
handle the different capabilities and merge/demerge those.

> OpenSyncFormatDuplicateFunc and OSyncFormatCopyFunc:
> What is the difference between this two function and when should I use
> them?

The copy function is inteded to make a 1:1 copy (also new to me :)). The
duplicate function generates also a new UID whichs have to be different to
the original UID. The later one get called if you have a conflict and
choose "duplicate entry".

> OSyncFormatRevisionFunc:
> This function is a big black hole to me. It is used e.g. in xmlformat.c
> but what is the intention of this function?

This function has to return the timestamp when the entry got changed the last
time. This got used also for conflict resultion, if someone hits "take
newer/latest entry".


All those three functions are optional. You don't have to implement them. They
should be already implemented for xmlformat format.. so you should write
first to conversion function to/from xmlformat-note.

Don't hesitate to ask if you have more question...
Thanks for all those question i guess i can put  all this into the new
whitepaper.

best regards,
Daniel

-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Opensync-devel mailing list
Opensync-devel@...
https://lists.sourceforge.net/lists/listinfo/opensync-devel