/usr/share/doc/buteo-syncfw-doc/plugin-guide.html is in libbuteosyncfw5-doc 0.7.21+16.04.20151216.1-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.9.1"/>
<title>ButeoSynchronizationFramework: Writing plugins for Synchronization Framework</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">ButeoSynchronizationFramework
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.9.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Writing plugins for Synchronization Framework </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#kinds-of-plugins">Kinds of plugins that Buteo supports</a></li>
<li class="level1"><a href="#create-plugin">Creating a plugin</a><ul><li class="level2"><a href="#generate-plugin-template-code">Instructions for generating a plugin</a></li>
</ul>
</li>
<li class="level1"><a href="#oop-plugins">Writing Out of process plugins</a></li>
<li class="level1"><a href="#libsyncml">Device sync with libsyncml</a><ul><li class="level2"><a href="#usb-sync">Sync over USB</a></li>
<li class="level2"><a href="#bluetooth-sync">Sync over bluetooth</a></li>
<li class="level2"><a href="#sailfish-N9-contacts">Synchronization of Contacts between Sailfish and N9</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="kinds-of-plugins"></a>
Kinds of plugins that Buteo supports</h1>
<ol type="1">
<li><b> Client plugins </b> Plugins which act as clients to services running outside the machine (device/PC/ tablet) domain. These plugins are loaded whenever there is a need for starting sync and are unloaded once done. 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.)</li>
<li><b> Server plugins </b> Server plugins are alive forever and act as server for clients that would like to connect to the server. A typical example of a server plugin is a SyncML server plugin that acts as a server for an external client</li>
<li><b> Storage plugins </b> A storage plugin enables a generic API for accessing the data from the device databases, like Contacts, File system, Calendar etc. These plugins can then be used across multiple protocols like Dropbox, Google services, Caldav etc.</li>
</ol>
<h1><a class="anchor" id="create-plugin"></a>
Creating a plugin</h1>
<p>The buteo-syncfw comes with a tools package to create template plugin code that will help the developer to quickly create plugins</p>
<p>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</p>
<h2><a class="anchor" id="generate-plugin-template-code"></a>
Instructions for generating a plugin</h2>
<p>boiler plate code. 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</p>
<p>To generate client plugin, run the command:</p>
<div class="fragment"><div class="line">./gen_template.py -c client-plugin.cfg -d <output dir> </div>
</div><!-- fragment --><p>To generate server plugin, run the command:</p>
<div class="fragment"><div class="line">./gen_template.py -c server-plugin.cfg -d <output dir> </div>
</div><!-- fragment --><p>To generate storage plugin, run the command:</p>
<div class="fragment"><div class="line">./gen_template.py -c storage-plugin.cfg -d <output dir> </div>
</div><!-- fragment --><h1><a class="anchor" id="oop-plugins"></a>
Writing Out of process plugins</h1>
<p>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 devised 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.</p>
<p>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</p>
<p>The following few lines have to be added to the .pro file to convert a .so plugin to a binary executable plugin</p>
<div class="fragment"><div class="line">TEMPLATE = app</div>
<div class="line">QT += dbus</div>
<div class="line">target.path = /usr/lib/buteo-plugins-qt5/oopp</div>
<div class="line"></div>
<div class="line">DEFINES += <span class="stringliteral">"CLASSNAME=MyPluginClassname"</span></div>
<div class="line">DEFINES += CLASSNAME_H=\\\<span class="stringliteral">"MyPluginClassname.h\\\"</span></div>
<div class="line"><span class="stringliteral">INCLUDE_DIR = $$system(pkg-config --cflags buteosyncfw5|cut -f2 -d'I')</span></div>
<div class="line"><span class="stringliteral"></span></div>
<div class="line"><span class="stringliteral">HEADERS += $$INCLUDE_DIR/ButeoPluginIfAdaptor.h \</span></div>
<div class="line"><span class="stringliteral"> $$INCLUDE_DIR/PluginCbImpl.h \</span></div>
<div class="line"><span class="stringliteral"> $$INCLUDE_DIR/PluginServiceObj.h</span></div>
<div class="line"><span class="stringliteral"></span></div>
<div class="line"><span class="stringliteral">SOURCES += $$INCLUDE_DIR/ButeoPluginIfAdaptor.cpp \</span></div>
<div class="line"><span class="stringliteral"> $$INCLUDE_DIR/PluginCbImpl.cpp \</span></div>
<div class="line"><span class="stringliteral"> $$INCLUDE_DIR/PluginServiceObj.cpp \</span></div>
<div class="line"><span class="stringliteral"> $$INCLUDE_DIR/plugin_main.cpp</span></div>
</div><!-- fragment --><p>In the above, replace "MyPluginClassname" with the name of your plugin class and the name of the header</p>
<p>If the plugin is a client plugin, add the following DEFINES, else <b>do not</b> add</p>
<div class="fragment"><div class="line">DEFINES += CLIENT_PLUGIN</div>
</div><!-- fragment --><p>Also, note that your plugin should have public inheritance from <a class="el" href="classButeo_1_1ClientPlugin.html" title="Base class for client plugins. ">Buteo::ClientPlugin</a></p>
<p>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:</p>
<div class="fragment"><div class="line">PLUGIN_DLL {</div>
<div class="line">...</div>
<div class="line"># DLL configuration (the same as your existing configuration)</div>
<div class="line">...</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line">PLUGIN_EXE {</div>
<div class="line">...</div>
<div class="line"># OOP plugin config</div>
<div class="line">...</div>
<div class="line">}</div>
</div><!-- fragment --><p>To generate the code for a specific configuration, you can run qmake like:</p>
<div class="fragment"><div class="line">qmake myplugin.pro CONFIG+=PLUGIN_EXE</div>
</div><!-- fragment --><h1><a class="anchor" id="libsyncml"></a>
Device sync with libsyncml</h1>
<p>libsyncml is a desktop based sync engine that support sync using SyncML protocol URL: <a href="https://libsyncml.opensync.org/">https://libsyncml.opensync.org/</a> It comes with a cmdline tool syncml-ds-tool to perform sync. Following instructions help in performing the sync over bluetooth and USB</p>
<p>Buteo works with libsyncml over USB as well as bluetooth. These instructions are w.r.t the sailfish OS, but as and when more Linux based OS's are supported, these instructions will be extended</p>
<h2><a class="anchor" id="usb-sync"></a>
Sync over USB</h2>
<ol type="1">
<li>Connect the Sailfish based device to your PC over USB.</li>
<li>Select the MTP mode when asked for a USB mode selection</li>
<li>From the PC (Ubuntu or a version supporting libsyncml), install libsyncml-utils (in debian, 'sudo apt-get install libsyncml-utils)</li>
<li>Run the following sync command for USB: <div class="fragment"><div class="line">sudo syncml-ds-tool -u 1 --identifier <span class="stringliteral">"PC Suite"</span> --sync text/x-vcard Contacts </div>
</div><!-- fragment --> Note: The command has to run as 'sudo', else you will have to add the USB device into your udev list</li>
<li>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</li>
</ol>
<h2><a class="anchor" id="bluetooth-sync"></a>
Sync over bluetooth</h2>
<ol type="1">
<li>Pair your bluetooth enabled PC/laptop with Sailfish based device. Also enable the bluetooth options of "connect automatically" and "trust"</li>
<li>Find out the bluetooth address of the sailfish based device by running the hcitool. <div class="fragment"><div class="line">hcitool scan </div>
</div><!-- fragment --></li>
<li>Run the following sync command: <div class="fragment"><div class="line">syncml-ds-tool -b <bluetooth address> 26 --identifier <span class="stringliteral">"PC Suite"</span> --sync text/x-vcard Contacts </div>
</div><!-- fragment --> 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)</li>
<li>The above command should fetch all the contacts in the Sailfish device to your PC and dump the output to the screen.</li>
</ol>
<h2><a class="anchor" id="sailfish-N9-contacts"></a>
Synchronization of Contacts between Sailfish and N9</h2>
<ol type="1">
<li>In N9, go to Settings -> Sync & Backup -> Sync -> Add new sync target (+ below)</li>
<li>Choose the Sailfish device in the list of bluetooth devices</li>
<li>Start sync </li>
</ol>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Dec 16 2015 19:19:26 for ButeoSynchronizationFramework by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.9.1
</small></address>
</body>
</html>
|