Subject: OSyncPluginConfig API: Summary and Porting instruction
Newsgroups: gmane.comp.misc.opensync.devel
Date: 2008-08-17 22:18:09 GMT (45 weeks, 5 days, 6 hours and 32 minutes ago)
Hi,
the OSyncPluginConfig API got kind of stable. There are some issues left, if
you found some - please file tickets.
First, some notes why we started to waste so much time on this:
The purpose of the OSyncPluginConfig API:
* make the update case for existing plugin configuraiton possible and easy
o no need to write for each plugin a separated version update script
o a common XSLT stylesheet could/should be enough to update all
plugin configurations
* make life easier of UI developers
o no need to write configuration parser for each plugin from scratch
o no need to read the plugin source code to understand the
undocumented plugin configuration!
* restrict the plugin developers to a "manageable" number of configuration
options ;)
o way to much people complainted so far about way to complex
configuration
---
What does the OSyncPluginConfig handle?
The Big-Picture:
http://www.opensync.org/attachment/wiki/PluginConfigXsd/common-plugin-xsd-DRAFT-v1.png?format=raw
(Description is obsolate...)
AdvancedOptions:
Not common plugin options implemented in OSyncPluginAdvancedOption interface.
Allows to have several AdvancedOption which are self-describing: Type, Name,
Displayname (how to represent in an UI), MaxSize, MaxOccurs, ValEnums, ...
Should be used for Options which don't fit in any other OSyncPluginConfig
interface.
Authentication:
Implemented in OSyncPluginAuthentication must be used by plugins to store
authentication information - like Username and Password. For later use there
is also the field "reference" which is intended to store some ID of
KWallet/GNOME-Key-Ring or other password managers, instead of the password.
The implementation of the proper password manager should be done by the
OpenSync Frontend consumer - OpenSync will only provide storing password in
an unsafe fashion by storing the password plaintext. Don't use this!
The interaction between Password Manager and Plugin process requires some
further research and development ...
Connection:
This is implemented in OSyncPluginConnection interface and must be used by
plugins get connection related settings. Frontends should also only use this
interface to do connection configuration of plugins.
Localization:
Plugin specific configuration about which encoding, timezone or language
should be used. (Hopefully this got used only with some old devices which
disappear soon...)
Resources:
Implemented in OSyncPluginResource. There can be several resource available,
but only one active/enabled resource per objtype.
Example: evolution/korganizer with several calendar/contact resources - all
those resources will be list in OSyncPluginResources. The users has to
select/configure via OpenSync Frontend/UI he/she want to sync with this
group.
The plugin has to report all available resources within the discover function,
using the OSyncPluginConfig interface. The corresponding formats of each
resource have to be store within a OSyncObjFormatSink. Even if a plugin
supports only fixed formats - the plugin must report those as
OSyncObjFormatSink within a Resource.
---
Quick & Dirty porting instructions:
- update your default configuration to OSyncPluginConfig schema
(check plugin_config.xsd)
- remove all your XML configuration parsing code
- use OSyncPluginConfig API instead
- remove osync_objtype_sink_add_objformat() calls
- remove osync_objtype_sink_num_objformats() calls
- remove osync_plugin_info_add_objtype() calls
- osync_plugin_info_get_config() returns now OSyncPluginConfig
- replace with osync_objtype_sink_new() with osync_plugin_info_find_objtype()
(may return NULL!): OpenSync will take care about OSyncObjTypeSink
allocation and registration, by loading coressponding format which are
enabled in OSyncPluginResource configuration..
- retrieve objformat configurations via OSyncPluginResource - look for
OSyncObjFromatSink
- if you're plugin supports only a single objformat per objtype - just
hardcode it. The discovery calls will take care that the
OSyncPluginResource() will contain correct ObjFormat information.
Make sure your discovery plugin function report all available resources!
Just call osync_plugin_find_active_resource(config, $objtype) - to get the
selected resource for the corresponding objtype within other plugin
functions.
Don't hesitate to ask if there are any question. I try to improve the API
documentation of this new interface within the next days...
best regards,
Daniel
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/