[cvs] [Wiki] created: SyncMLCustomBackend

Fri Feb 15 12:48:37 UTC 2008

jan  Fri, 15 Feb 2008 07:48:37 -0500

Created page: http://wiki.horde.org/SyncMLCustomBackend

The following is an archive copy from http://fourmont.org/drupal/node/2
which seems to have gone, at least temporarily.

+ New SyncML version 0.7.0

Sun, 01/14/2007 - 18:02 — karsten

SyncML (Synchronization Markup Language) is a protocol standard defined by
the Open Mobile Alliance for platform-independent information
synchronization.

SyncML is mostly used as a method to synchronize contact and calendar
information between some type of handheld device and a computer (personal,
or network-based service), such as between a mobile phone and a Horde
installation.

For some time now I've been working on a PHP PEAR package to provide a
SyncML implementation. This package is part of the [http://www.horde.org
Horde groupware application], but is intended to be useful independent from
Horde as well.

The new version 0.7.0 is a major step towards separating the SyncML part and
the backend (Horde) part. There's now an example SQL backend that works with
plain sql tables and does not require Horde at all.

The aim of the SyncML package is to provide a robust implementation of the
SyncML protocol to allow groupware applications (especially but not limited
to Horde) providing the SyncML functionality of replication their data with
PDAs, phones and Outlook.
To allow integration with different groupware apps, the SyncML protocol part
needs to be separated from the part communicating with the actual groupware
application.
This is done by means of a Backend class that contains all the backend
application (horde) dependent code.

Until now, this has been more a vague idea than concrete code but 0.7.0 does
change that:
there's now an (abstract) {{!SyncML_Backend}} class in {{Backend.php}}, that
defines and documents all the functions a Backend must provide. For some
functionality like session handling and logging the Backend class does also
provide a default implementation. Plese read the documentation at the
beginning of {{Backend.php}}.

Individual backend implementation are derived from {{!SyncML_Backend}} and
reside in the {{Backend/}} directory. Currently there are two such backends:

+++ Horde backend

This backend allows replication with the Horde groupware suite, see
http://www.horde.org. Development of the SyncML package is done as part of
the Horde development, so the Horde backend is the one best tested and most
heavily used.

+++ SQL backend

This is new for 0.7.0 and more or less all changes in this release were done
to allow creation of this class. The SQL backend is some kind of reference
implementation of a backend that uses only plain database tables. The
database is directly accessed using the PEAR MDB2 package, successor to the
pear DB package. The SQL backend does not require a Horde installation at
all. Developers who want to create their own backend can have a look at the
SQL backend and take it as a starting point for their own implementation. It
provides almost all the functionality of a backend server: the only thing it
lacks is conversion of different content types: for example phone1 may store
an address book entry with content type {{text/vcard}} (vcard3.0, as of
rfc2426) while phone2 then needs this entry presented as {{text/x-vcard}}
(vcard2.1, as of http://www.imc.org). The SQL backend can't do such a
conversion. However actual backends (like Horde) normally provide it as they
have to "understand" the data's content rather than just store it.

++ Structural Changes

The backend is one end point of the SyncML package. The other end is the
place where the HTTP request gets into the System. Prior to 0.7.0 this has
been a bit confusing as some of the logic was done in the Horde RPC package,
from there it went to {{!SyncML.php}} and in there to two other handlers.
This has been greatly simplied. As of 0.7.0 there is one central function in
{{!SyncML.php}}:
<code type="php">
SyncML_HandleRequest($request, $contentType, $backend =
'Horde',$backendparms = array())
</code>
This one you provide with a HTTP request and its content type:
{{application/vnd.syncml+xml}} or {{application/vnd.syncml+wbxml}} as
provided by the client.
The function does all the processing, WBXML en- and decoding if necessary
and returns the XML or WBXML data the can be passed on to the client.

The SyncML package now only requires the XML_WBXML package, all dependencies
to other Horde packages have been removed. Of course individual backends may
require additional packages: MDB2 for the SQL backend and a complete Horde
installation for the Horde backend.

There's one caveat at the moment: if you plan using one of the
[http://www.funambol.org Funambol clients] for syncing with Outlook,
Blackberry or !PocketPC, you also need the Horde pear packages iCalendar,
String and NLS.

++ How things work

When the {{!SyncML_HandleRequest}} in {{!SyncML.php}} is invoked, it creates
a backend with the given parameters and an instance of class
{{!SyncML_ContentHandler}}. The {{process()}} method of this class does the
processing: it creates either an XML parser or an WBXML decoder which then
parse the (WB)XML and call the {{startElement()}}, {{endElement()}} and
{{characters()}} callback functions of {{!SyncML_ContentHandler}}. The
{{startElement()}} function creates appropriate subclasses of
{{!SyncML_Command}} like {{!SyncML_Command_Alert}} when an {{<Alert>}} is
received. These have their own {{startElement()}}, {{endElement()}} and
{{characters()}} which are called and collect the individual XML data inside
the commands. (The {{!SyncHdr}} is considered a command here, too). The
{{endElement()}} of {{!SycML_HandleRequest}} then invokes
{{handleHeader()}}, {{handleCommand()}} or {{handleEnd()}}, to deal with the
header, individual commands or the end of the SyncML request.

To create the (WB)XML output, there's a {{!SyncML_XMLOutput}} singleton.
This class creates all the response elements like the response
{{<!SyncHdr>}} by calling {{outputHeader()}}. To produce XML, it uses the
{{XML_WBXML_ContentHandler}} class which, despite its name, has nothing to
do with WBXML but creates plain XML output. If the desired output is WBXML,
{{XML_WBXML_Encoder}} is used. It has the same interface as the
{{XML_WBXML_ContentHandler}} but produces WBXML.

Most of the business logic is inside {{!SyncML_Sync}} class. During one sync
session more than one database can be synced, like calendar and address
book. The {{!SyncML_Sync}} class handles the {{Sync}} of exactly one
database. It is setup by the {{Alert}} command and then does most of the
processing when responding to the {{Sync}} command.

For more details about the SyncML protocol see the SyncML spec at
http://www.openmobilealliance.org/tech/affiliates/syncml/syncmlindex.html.
The document //!SyncML Sync Protocol, v1.1 (pdf)// is the most relevant one:
it describes how a sync session works.

++ The test framework

The test framework consists of a test script and individual test cases. A
test case for SyncML is basically a recording of a successful sync session.
The {{testsync.php}} script can then replay such a recording by sending the
recorded client requests to the SyncML package and check if the response
matches the one in the original recording. Actually the test script has to
do quite a bit of magic to make this work: it has to simulate entries in the
backend so the server returns them on the next sync and it has to adapt
between newly created IDs and IDs used in the recording.

The big advantage of the test framework is that a test case recorded with
one backend can be used with any other backend implementation. So when
developing a new backend, you can use the test framwork to verify that your
implementation is correct.

++ How to setup a simple SyncML server

Setting up a simple SyncML server using the SyncML package and the Sql
backend is as simple as this:

1. Install pear packages for MDB2 and MDB2 database drivers:
<code>
pear install MDB2_Driver_mysql MDB2_Driver_mysql
</code>

2. Install the SyncML package and the XML_WBXML package from
http://pear.horde.org:
<code>
pear channel-discover pear.horde.org; pear install --force -c pear.horde.org
SyncML XML_WBXML
</code>

3. If you want to use the Funambol clients, you also need iCalendar, String
and NLS:
<code>
pear install --force -c pear.horde.org iCalendar String NLS
</code>

4. Create a database in your database engine (like mysql) as described in
{{Backend/Sql.php}}:

<code type="php">
require_once 'SyncML.php';

// Backend Setup:
$backend = 'Sql';
$backend_parms = array('dsn' => 'mysql://syncml:password@localhost/syncml',
// adjust as required
                       'debug_dir' => '/tmp/sync', // debug output to this
dir, must be writeable be web server
                       'debug_files' => true, // log all (wb)xml packets
received or sent to debug_dir:
                       'log_level' => PEAR_LOG_DEBUG); // log everything

$response = SyncML_HandleRequest($GLOBALS['HTTP_RAW_POST_DATA'],
$_SERVER['CONTENT_TYPE'], $backend, $backend_parms)
if (is_a($response, 'PEAR_Error')) {
    header('HTTP/1.0 500 Internal Server Error');
    exit;
}

/* Return the response to the client. */
header('Content-Type: ' . $_SERVER['CONTENT_TYPE']);
header('Content-length: ' . strlen($response));
header('Accept-Charset: UTF-8');
echo $response;
</code>

++ Where to get the SyncML package

The SyncML package is part of the Horde framework. At the moment you have to
download the framework from htt://www.horde.org to obtain the SyncML and
WBXML packages. It'll be included in the pear channel server as soon as
possible to allow installation using the PEAR installer.

If you have any questions, send me a message to karsten __at__ horde _dot_
org.