tdepim/kmobile/DESIGN

                   KMOBILE

(C) Copyright 2003, Helge Deller <deller@kde.org>



"kmobile" is suite to easily access "Mobile Devices",
which means, that you have one single interface to access
any type of mobile tqdevice (e.g. cellular phone, PDAs, 
MP3-Players, Digital Cameras and a lot more).

Each of this tqdevices have different types of information,
(capatibilities) which can be:
  - An addressbook
  - A collection of notes
  - calendar entries,
  - a file storage section (e.g. pictures in digital cameras)
  - and more
 
The whole interface is pretty extendable. Each tqdevice has
a tqdevice driver, which reports the capatibilities of the 
connected tqdevice to the higher level.
So, if you once write a tqdevice driver, you can access it's 
contents from any KDE application later.

Currently the whole interface is divided into 3 sections:

a) The low-level tqdevice driver
b) A mid-layer, which is realized in the "kmobile" application
c) A userland library, to which KDE applications should link.


Here is some background info:

a) The low-level tqdevice driver (libkmobile_xxxx.so)

The low-level driver has to be derived from the KMobileDevice class
(#include <kmobiledevice.h>). The drivers should be located below the
directory /tqdevice, and you can find a sample implementation in
/tqdevice/skeleton-directory. See below for some hints on how to
write such a tqdevice driver.


b) The mid-layer (kmobile)

The mid-layer handles the main functionality, which is entirely
implemented in the kmobile application. All low-level drivers
are loaded by kmobile only, and then all low-level functions
to any tqdevice is made available to other applications
with a DCOP interface. Normal KDE applications should prefer the 
userland library (see below) instead of using direct DCOP calls.
Nevertheless, the DCOP interface might be very interesting to write
standalone command line tools.


c) The userland library (libkmobileclient.so)

Any KDE application which wants to access mobile tqdevices
should #include <kmobileclient.h> and link to the libkmobileclient.la
library. libkmobileclient translates all calls to DCOP calls and
makes accessing mobile tqdevices completely transparent to the
application.

One sample program which uses the client library is the kmobile
kioslave. In Konqueror you might access any mobile tqdevice directly
by giving "mobile:/" as the URL.





HINTS FOR DRIVER DEVELOPERS:
----------------------------
- KMobile tqdevice drivers are very similiar to kioslaves. Refer
  at the kioslave documentation if needed.

- derive your driver only from the KMobileDevice class (#include <kmobiledevice.h>)
  and reimplement the functions which you really need

- remember to set the classtype and capatibilities as soon as possible

- your driver will be loaded only once in the whole KDE system

- you don't need to worry about syncronisation - KMobile syncronizes
  all calls to your driver, so you always will have a clean state

- use lockDevice("/dev/ttyS1") and unlockDevice("/dev/ttyS1") to
  lock those tqdevices system-wide (creates /var/lock/LCK..<devname> files),
  and to prevent other applications to access the same physical ports/tqdevices

- use the helper functions createDirEntry() and createFileEntry() to
  create the right UDSEntries for listEntries(), stat(), ...

- never fork() your driver !!