Overview
--------

                                    -------------
                                   |  DMclient   |
                                   | application |
                                    -------------
                                          |
                                   +-------------+
                                   |   dmclient  |--------+
                                   |   library   | SyncML |
                                   +-------------|  RTK   |
                                          |      +--------+
                    ______________________|____________________________
                   |               |             |          |        |
              -----------      ---------      -------     -----    -----
             | DevDetail |    | DevInfo |    | DMAcc |   | ... |  | ... |
             |    MO     |    |    MO   |    |  MO   |   | MO  |  | MO  |
              -----------      ---------      -------     -----    -----


libdmclient implements the client-side of OMA DM 1.2 protocol. It provides high-level APIs. The main functions are:
  - omadmclient_session_open()
      to open a DM session either to a specified server or by parsing a Wap Push payload.
  - omadmclient_get_next_packet()
      to retrieve a complete SyncML packet to be sent to the server
  - omadmclient_process_reply()
      to make the library process the reply received from the server
For the SyncML parsing, we are using the SyncML Reference Toolkit published by OMA.

The DMclient application is platform specific. Its role is to open the communicate with the server, receive Wap Push messages and display some UI.
A DM Client algorithm is:

    omadmclient_session_init()
    omadmclient_session_add_mo()
    omadmclient_session_open()
    while (packet = omadmclient_get_next_packet())
    {
        http_send(packet)
        packet2 = http_receive()
        omadmclient_process_reply(packet2)
    }
    omadmclient_session_close()

One of omadmclient_session_init() parameters is a callback called when there is some UI to display.

The MOs are plugins. They are loaded by the DM client using the omadmclient_session_add_mo() API.

The MO interface contains 9 APIs apart from the classic open and close:
   - isNode() to test the existence of a node and determine if it is a leaf or an interior node.
   - findURN() to find the URLs associated to an URN
   - get() to retrieve a node value or list of children along with its meta data.
   - set() to set a node's value or create a node.
   - getACL() and setACL() to get and set the Access Control List of a node.
   - rename(), delete() and exec()

All the access rights check, URI parsing and syntax validation is done by the library. The MOs can be really simple.

libdmclient comes with a command-line dmclient application and some test MOs. The MOs are mostly returning hard-coded values.


Source Layout
-------------

-+- dmcore              (the dmclient library)
 |    |
 |    +- include        (public header files either for using the lib or for MOs)
 |    |
 |    +- src            (source files of the lib)
 |
 +- externals
 |    |
 |    +- SyncMLRTK      (the SyncML Reference Toolkit published by OMA)
 |    |
 |    +- libmd5-rfc     (the libmd5-rfc available at http://sourceforge.net/projects/libmd5-rfc/)
 |
 +- tests
 |    |
 |    +- client         (a command-line test OMA DM client)
 |    |
 |    +- mgtobj         (test MOs for the dmclient library)
 |    |    |
 |    |    +- DevDetail (contains hard-coded values)
 |    |    |
 |    |    +- DevInfo   (contains hard-coded values)
 |    |    |
 |    |    +- DmAcc     (contains hard-coded values)
 |    |    |
 |    |    +- Inbox     (empty MO)
 |    |    |
 |    |    +- Memory    (stores added nodes in memory)
 |    |    |
 |    |    +- Storage   (stores added nodes in a SQL DB)
 |    |    |
 |    |    +- utils     (utility functions for hard-coded nodes)
 |    |
 |    +- windows        (test client and plugins for Windows)
 |
 +- windows             (build system for Windows)


Compiling on Linux
------------------

libdmclient requires some packages:
  - autoconf automake libtool gcc make
      for the build system

Two other packages are optionnal:
  - libcurl-devel
      for the test client
  - sqlite-devel
      for test Storage MO

In the source top directory, run the following commands:
    autoreconf -i
    ./configure [options]
    make
    make install

Specific configure options are:
  --enable-tests
      build the test client and MOs. No by default.


Install: libdmclient.so is installed in ${prefix}/lib/dmclient


Compiling on Windows
--------------------

You will need Visual Studio. The free (as in beer) Express version is enough.

Open the VS project libdmclient.vcxproj in the cloned repository windows folder. Build your solution. The DLL will be under windows/Debug or windows/Release depending on your configuration.

These VS projects were created using Visual Studio 2012. If you are using a different version, you may need to change the Platform Toolset setting. Open the Properties dialog for libdmclient project. The setting is under Configuration Properties/General.


Testing
-------
On Linux if configure was run with the option '--enable-tests', 'make install' will build and install some test MOs. The command-line dmclient application is ${prefix}/bin/testdmclient.
On Windows a test console application and some plugins can be found under tests/windows. To build them, open the VS project testdmclient.vcxproj. The build output is in the folder as libdmclient.dll

Usage: testdmclient [-w] [-f FILE | -s SERVERID]
  -w	use WBXML
  -f	use the file as a server's packet
  -s	open a DM session with server SERVERID
Options f and s are mutually exclusive.

testdmclient launches a DM session with the server "SERVERID". If "SERVERID" is not specified, "funambol" is used by default. The DmAcc test MO contains a DM account for "funambol". Settings for it can be modified in tests/mgtobj/DmAcc/plugin_dmacc.c
the '-f' option is used to test libdmclient handling of specific SyncML packet stored in a file. In this case, there is no connection to any server and the authentification mechanism is disabled.
testdmclient outputs the UI alerts on stdout ans dumps the sent and received packets on stderr.


Usage
-----
All the libdmclient functions are defined in dmcore/include/omadmclient.h
The plugin interface is defined in dmcore/include/omadmtree_mo.h