OpenSync Glossary

This page explains some terms and concepts used in OpenSync. It was generated from an email discussion (to be found at http://thread.gmane.org/gmane.comp.misc.opensync.devel/1664).

Note that many of the items discussed here are specific to the trunk (ie, development, 0.3x and above) version of OpenSync.

plugin

Something that is loaded by the OpenSync framework from a dynamic library to implement either a sync member or format.

plugin info

A data structure filled in by a plugin when it is loaded that describes its capabilities in terms of the formats or sinks it supports. In the OpenSync API this is separate from the plugin:

OSyncPlugin: carries version and name and description data about the plugin as well as startup flags.

OSyncPluginInfo: carries pointers and links to sinks and general functionality that the plugin supports, required to know during operation. It can be used as a top level structure by the plugin to "dig down" to find sink, format, and capability data.

sink

Implemented/provided by a sync plugin, a sink is the "final" (from OpenSync's point of view) source or destination for data of a specific object type. Each sink handles a single object type.

object format

How the object is represented, eg. internal XML format (either as a parsed binary structure or as a flat text document), or vcalendar/icalendar and friends, etc.

object type

What the object is: event, contact, todo, note, etc. For each object type there are multiple formats possible. Conversion can change the format of an object but never its type.

There is also a special object format/type "file" (this needs further explanation).

object type sink

Same as "sink" above. This term just clarifies that sinks are per-object-type.

format

See object format, above.

xml format

Opensync's internal XML representation of the standard event/contact/todo/note types. This is specified by the schemas in misc/schemas/*.xsd, implemented by the converters to/from the vformats (in the vformat plugin), and used internally by the merger and archive code. Generally format converter plugins will convert to/from this format.

environment, format environment

Data structures that exist when a plugin is loaded/registered, and used for registering user data and managing callbacks etc.

The format environment contains a list of all registered object formats, converters and filters. It is mostly internal to OpenSync.

merger

Many devices (eg. mobile phones) don't support or store all fields for an object, eg. for an event my mobile only stores the name but not the description or location. If I sync my PC calendar to my mobile, and then change the time of an event on my mobile, the merger code takes care that the new time from the mobile phone is merged together with the old description and location that weren't stored on the phone.

In previous versions of OpenSync this wasn't supported, so you were limited by the "lowest common denominator" of devices you synced with.

mapping

Code/module/database to keep track of which unique IDs (UIDs) on which devices correspond to each other.

For example, on some cellphones entries are stored in numbered slots. If an entry is changed on the phone, the corresponding entry should be changed on the PC in the next sync. The mapping code remembers that the entry with UID xyz on my PC has "UID" (really position) 37 on the phone, and matches changes accordingly.

capability

For the merger code to work, it needs to know what "fields" within an object type are supported by each device in a sync group. The capabilities are a list of XML fields for each object type that a device handles.

xml field

Individual field in an object, in the internal XML format. Eg. Location, Summary, DateTime, RecurrenceRule, etc.

database

The merger and mapping code needs to store the full data of each object and the mapping of UIDs between devices. This all goes into sqlite databases in ~/.opensync. The database code manages that, and provides abstraction should it be desirable to switch to a different database backend in the future.

group

Everything involved in a sync operation. Eg. if I want to sync my phone to KDE, I create a sync group with moto-sync and kdepim members. You can have multiple sync groups managed by opensync. Configuration is done on a per-plugin per-group basis. Each group has its own merger, mapping and archive databases.

client

The OpenSync engine is a thread that goes through several phases. First it initialises the plugins, then they connect, then it asks them to report changes, then it controls the mapping/merging and sends changes out to the other plugins, etc. The plugins all run in separate threads (actually separate processes communicating over pipes IIRC?) and are "clients" of the engine. That is, they do everything in response to commands from the engine.

There is also separately server/client in the sense of syncml, which confuses things a bit.

anchor

The Anchor module stores some kind of data (called an "anchor") from the Member. This "anchor" gets updated once on each sync. If the "anchor" doesn't match on the next sync a slow-sync is triggered.

Example:

A random string gets generated by the member on each sync, eg. XYZ, and is stored as the "anchor". If the member didn't get reset or synced somewhere else in the meantime, on the beginning of the next sync the anchor and the string are compared and match: XYZ == XYZ. Regular sync and new random string: ABC, but this time the member got synced with another system and generated a new random string: DEF. On the next local sync the anchor is compared with the member stored string: ABC != DEF - the "anchor" doesn't match with the member string. To avoid any data loss and to get the changed entries of the previous sync with the other system, a slow-sync is required.

Example implementation in plugins: syncml, palm-sync, irmc-sync, ...

archive

The archive is a persistent store of all the objects seen/handled in a sync group. It is necessary for the merger code to work.

change

Objects move between group members (plugins) as changes. A change can either be added, deleted, or modified. If it is added or modified it carries the full data of the object (there are no diffs). The object format of a change can be converted along the way between plugins.

converter

A piece of code that converts some data from one object format to another, ie. what a format plugin does. If a direct conversion between two object formats isn't available, converters are chained together.

hashtable

Some devices (my phone, again) can't tell you if their data has changed, just what it is currently. To decide if each entry on the phone is new, modified, or unchanged, the hashtable is used to store a hash of that entry's data. This is stored in another sqlite database. Not all plugins need to use the hashtable.

error

Error objects are used to report and propagate errors between OpenSync functions. They carry an error code as well as an error message.

data

1. Generally, the object data associated with a change.
2. The name for a special object type which is a "wildcard" that refers to every object type. If you want to write a plugin which should handle all object types in a generic way, you would register a sink with "data" instead of registering sinks for a set list of specific object types.

discovery

The process of connecting to devices and finding out what object types and capabilities they support. For some plugins this information is static (ie. they always handle the same object types and capabilities), but for others it is detected on the fly, eg. the moto-sync plugin connects to the phone and determines if it supports an extended calendar format.

Discovery happens once when a sync group is created. Unless the devices change it shouldn't be necessary to rediscover later.