Sync plugins

Types of plugins

There are three kinds of sync plugins

1. Client plugin
2. Server plugin
3. Storage plugin

1. The client plugins as the name indicates is the client side part of a synchronization activity. For example, synchronization with Google services from the device would involve a client plugin and Google services acting as a server. The client plugins would be loaded on demand and would be unloaded once the sync activity is over. More than one client plugin can be loaded at any point of time, provided that they deal with different kinds of storages (contacts, calendar, notes etc.)

2. The server plugins enable a server role for the synchronization. A server plugin acts as a server for an external client to connect to. An example of a server plugin is a SyncML sync between two devices. When sync happens between two devices, one of the devices has to act as a server. The protocol would be responsible for deciding the roles between the two devices. Whenever a device acts as a server, the server plugin is responsible for handling the server side activities. A server plugin is not unloaded for ever, since any client can connect to it at any point of time

3. A storage plugin is one that enables synchronization of a particular storage for a sync session. For example, a contacts storage plugin will be loaded for the duration of the sync session, would perform the sync activities between the sync agent (protocol) and the database (like store/retrieve) and gets unloaded once the sync session is over.

Creating a plugin

The buteo-syncfw comes with a tools package to create template plugin code that will help the developer to quickly create plugins

The tool uses Cheetah (www.cheetahtemplate.org/‎) template library to generate the templates. One can install cheetah in Ubuntu using command: 'sudo apt-get install python-cheetah'. Python 2.7 or greater is required

Instructions for generating template

The configuration files corresponding to a client/server/storage have to be filled-in with the appropriate information. Each of the fields in the config files are marked with MANDATORY/OPTIONAL. Info about the fields is provided in the config files

To generate client plugin, run the command:

./gen_template.py -c client-plugin.cfg -d <output dir>

To generate server plugin, run the command:

./gen_template.py -c server-plugin.cfg -d <output dir>

To generate storage plugin, run the command:

./gen_template.py -c storage-plugin.cfg -d <output dir>

Writing Out of process plugins

Buteo syncfw version 0.1.0 supported only dynamic link library plugins which the framework loads into the same process memory as msyncd. This archicture has a problem that if any one of the plugin misbehaves (crashes, for example), msyncd would also crash and there is a probability that it would not recover. To avoid such situations, an out of process plugin architecture was deviced and implemented. In this architecture, each of the plugins would be running as separate processes and msyncd process would interact with each of the processes to handle the sync life cycle and operations.

In the new architecture, there is no need to modify any of the existing plugin code. The only change that needs to be done is in the .pro files of each of the plugins

The following few lines have to be added to the .pro file to convert a .so plugin to a binary executable plugin

TEMPLATE = app
QT += dbus
target.path = /usr/lib/buteo-plugins-qt5/oopp
DEFINES += "CLASSNAME=MyPluginClassname"
DEFINES += CLASSNAME_H=\\\"MyPluginClassname.h\\\"
INCLUDE_DIR = $$system(pkg-config --cflags buteosyncfw5|cut -f2 -d'I')

HEADERS += $$INCLUDE_DIR/ButeoPluginIfAdaptor.h   \
           $$INCLUDE_DIR/PluginCbImpl.h           \
           $$INCLUDE_DIR/PluginServiceObj.h

SOURCES += $$INCLUDE_DIR/ButeoPluginIfAdaptor.cpp \
           $$INCLUDE_DIR/PluginCbImpl.cpp         \
           $$INCLUDE_DIR/PluginServiceObj.cpp     \
           $$INCLUDE_DIR/plugin_main.cpp

In the above, replace "MyPluginClassname" with the name of your plugin class and the name of the header

If the plugin is a client plugin, add the following DEFINES, else do not add

DEFINES += CLIENT_PLUGIN

Also, note that your plugin should have public inheritance from Buteo::ClientPlugin (or Buteo::ServerPlugin)

If you want your existing plugin dll configuration to exist with the out of process plugin configuration, the good way is to add another configuration to your .pro file. The config would look like:

PLUGIN_DLL {
...
# DLL configuration (the same as your existing configuration)
...
}

PLUGIN_EXE {
...
# OOP plugin config
...
}

To generate the code for a specific configuration, you can run qmake like:

qmake myplugin.pro CONFIG+=PLUGIN_EXE

Sync with libsyncml

[libsyncml ref]

Buteo works with libsyncml over USB as well as bluetooth.

Following are the sequence of steps to perform this sync operation over USB

1. Connect the Sailfish based device to your PC over USB.
2. Select the MTP mode when asked for a USB mode selection
3. From the PC (Ubuntu or a version supporting libsyncml), install libsyncml-utils (in debian, 'sudo apt-get install libsyncml-utils)
4. Run the following sync command for USB:

     sudo syncml-ds-tool -u 1 --identifier "PC Suite" --sync text/x-vcard Contacts 

    Note: The command has to run as 'sudo', else you will have to add the USB device into your udev list
5. The above command should fetch all the contacts in the Sailfish phone to your PC and dump the output to the screen. For more options of syncml-ds-tool, look at its help or the libsyncml website

For synchronizing of contacts over bluetooth, below are the steps

1. Pair your bluetooth enabled PC/laptop with Sailfish based device. Also enable the bluetooth options of "connect automatically" and "trust" 
2. Find out the bluetooth address of the sailfish based device by running the hcitool.

    hcitool scan 

3. Run the following sync command:

    syncml-ds-tool -b <bluetooth address> 26 --identifier "PC Suite" --sync text/x-vcard Contacts 

   26 is the channel number of the SyncML bluetooth profile
   Replace <bluetooth address> with the bluetooth address of your sailfish device (something like B4:EE:D4:F6:19:E7)
4. The above command should fetch all the contacts in the Sailfish device to your PC and dump the output to the screen.

For synchronization of Contacts over bluetooth and N9, below are the steps:

1. In N9, go to Settings -> Sync & Backup -> Sync -> Add new sync target (+ below)
2. Choose the Sailfish device in the list of bluetooth devices
3. Start sync

--Kavuri 08:47, 19 November 2013 (UTC)