\documentclass{article}
\usepackage{ulem}
\usepackage{graphicx}
\usepackage{hyperref}
\pagestyle{headings}
\begin{document}
\section{The following is an archive copy from <a href="http://fourmont.org/drupal/node/2">http://fourmont.org/drupal/node/2</a> which seems to have gone, at least temporarily.}
\part{New <a href="https://wiki.horde.org/SyncML">SyncML</a> version 0.7.0}
Sun, 01/14/2007 - 18:02  karsten

<a href="https://wiki.horde.org/SyncML">SyncML</a> (Synchronization Markup Language) is a protocol standard defined by the Open Mobile Alliance for platform-independent information synchronization.

<a href="https://wiki.horde.org/SyncML">SyncML</a> 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 <a href="https://wiki.horde.org/SyncML">SyncML</a> implementation. This package is part of the <a href="http://www.horde.org">Horde groupware application</a>, but is intended to be useful independent from Horde as well.

The new version 0.7.0 is a major step towards separating the <a href="https://wiki.horde.org/SyncML">SyncML</a> 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 <a href="https://wiki.horde.org/SyncML">SyncML</a> package is to provide a robust implementation of the <a href="https://wiki.horde.org/SyncML">SyncML</a> protocol to allow groupware applications (especially but not limited to Horde) providing the <a href="https://wiki.horde.org/SyncML">SyncML</a> functionality of replication their data with PDAs, phones and Outlook.<br />
To allow integration with different groupware apps, the <a href="https://wiki.horde.org/SyncML">SyncML</a> protocol part needs to be separated from the part communicating with the actual groupware application.<br />
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:<br />
there's now an (abstract) \texttt{!SyncML\_Backend} class in \texttt{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 \texttt{Backend.php}.

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

\subsection{Horde backend}
This backend allows replication with the Horde groupware suite, see <a href="http://www.horde.org">http://www.horde.org</a>. Development of the <a href="https://wiki.horde.org/SyncML">SyncML</a> package is done as part of the Horde development, so the Horde backend is the one best tested and most heavily used.

\subsection{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 \texttt{text/vcard} (vcard3.0, as of rfc2426) while phone2 then needs this entry presented as \texttt{text/x-vcard} (vcard2.1, as of <a href="http://www.imc.org\">http://www.imc.org\textbackslash\{\}</a>). 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.

\section{Structural Changes}
The backend is one end point of the <a href="https://wiki.horde.org/SyncML">SyncML</a> 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 \texttt{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 \texttt{SyncML.php}:

<pre><code class="language-php">
SyncML\_HandleRequest(\$request, \$contentType, \$backend = 'Horde',\$backendparms = array())
</code></pre>
This one you provide with a HTTP request and its content type: \texttt{application/vnd.syncml+xml} or \texttt{application/vnd.syncml+wbxml} as provided by the client.<br />
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 <a href="https://wiki.horde.org/SyncML">SyncML</a> 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 <a href="http://www.funambol.org">Funambol clients</a> for syncing with Outlook, Blackberry or PocketPC, you also need the Horde pear packages iCalendar, String and NLS.

\section{How things work}
When the \texttt{!SyncML\_HandleRequest} in \texttt{SyncML.php} is invoked, it creates a backend with the given parameters and an instance of class \texttt{!SyncML\_ContentHandler}. The \texttt{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 \texttt{startElement()}, \texttt{endElement()} and \texttt{characters()} callback functions of \texttt{!SyncML\_ContentHandler}. The \texttt{startElement()} function creates appropriate subclasses of \texttt{!SyncML\_Command} like \texttt{!SyncML\_Command\_Alert} when an \texttt{<Alert>} is received. These have their own \texttt{startElement()}, \texttt{endElement()} and \texttt{characters()} which are called and collect the individual XML data inside the commands. (The \texttt{SyncHdr} is considered a command here, too). The \texttt{endElement()} of \texttt{!SycML\_HandleRequest} then invokes \texttt{handleHeader()}, \texttt{handleCommand()} or \texttt{handleEnd()}, to deal with the header, individual commands or the end of the <a href="https://wiki.horde.org/SyncML">SyncML</a> request.

To create the (WB)XML output, there's a \texttt{!SyncML\_XMLOutput} singleton. This class creates all the response elements like the response \texttt{<SyncHdr>} by calling \texttt{outputHeader()}. To produce XML, it uses the \texttt{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, \texttt{XML\_WBXML\_Encoder} is used. It has the same interface as the \texttt{XML\_WBXML\_ContentHandler} but produces WBXML.

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

For more details about the <a href="https://wiki.horde.org/SyncML">SyncML</a> protocol see the <a href="https://wiki.horde.org/SyncML">SyncML</a> spec at <a href="http://www.openmobilealliance.org/tech/affiliates/syncml/syncmlindex.html">http://www.openmobilealliance.org/tech/affiliates/syncml/syncmlindex.html</a>.<br />
The document \textit{SyncML Sync Protocol, v1.1 (pdf)} is the most relevant one: it describes how a sync session works.

\section{The test framework}
The test framework consists of a test script and individual test cases. A test case for <a href="https://wiki.horde.org/SyncML">SyncML</a> is basically a recording of a successful sync session. The \texttt{testsync.php} script can then replay such a recording by sending the recorded client requests to the <a href="https://wiki.horde.org/SyncML">SyncML</a> 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.

\section{How to setup a simple <a href="https://wiki.horde.org/SyncML">SyncML</a> server}
Setting up a simple <a href="https://wiki.horde.org/SyncML">SyncML</a> server using the <a href="https://wiki.horde.org/SyncML">SyncML</a> package and the Sql backend is as simple as this:

\begin{itemize}
\item Install pear packages for MDB2 and MDB2 database drivers:


\end{itemize}
<pre><code>
pear install MDB2\_Driver\_mysql MDB2\_Driver\_mysql
</code></pre>
\begin{itemize}
\item Install the <a href="https://wiki.horde.org/SyncML">SyncML</a> package and the XML\_WBXML package from <a href="http://pear.horde.org">http://pear.horde.org</a>:


\end{itemize}
<pre><code>
pear channel-discover pear.horde.org; pear install --force -c pear.horde.org SyncML XML\_WBXML
</code></pre>
\begin{itemize}
\item If you want to use the Funambol clients, you also need iCalendar, String and NLS:


\end{itemize}
<pre><code>
pear install --force -c pear.horde.org iCalendar String NLS
</code></pre>
\begin{itemize}
\item Create a database in your database engine (like mysql) as described in \texttt{Backend/Sql.php}:


\end{itemize}
<pre><code class="language-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

// Not all phpinstalls have http\_raw\_post\_data set, ini-config needed.
// Is it also deprecated in later versions? Well, php://input works.
if( isset(\$GLOBALS['HTTP\_RAW\_POST\_DATA']) ) 
    \$input = \$GLOBALS['HTTP\_RAW\_POST\_DATA'];
else
    \$raw\_post = file\_get\_contents('php://input');

\$response = SyncML\_HandleRequest(\$input, \$\_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></pre>
\section{Where to get the <a href="https://wiki.horde.org/SyncML">SyncML</a> package}
The <a href="https://wiki.horde.org/SyncML">SyncML</a> package is part of the Horde framework. At the moment you have to download the framework from htt://www.horde.org to obtain the <a href="https://wiki.horde.org/SyncML">SyncML</a> 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 <u>at</u> horde \_dot\_ org.

\end{document}
