Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 96 insertions, 0 deletions

diff --git a/kmobile/DESIGN b/kmobile/DESIGN
new file mode 100644
index 000000000..287a3d9a2
--- /dev/null
+++ b/kmobile/DESIGN
@@ -0,0 +1,96 @@
+
+                   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 device (e.g. cellular phone, PDAs, 
+MP3-Players, Digital Cameras and a lot more).
+
+Each of this devices 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 device has
+a device driver, which reports the capatibilities of the 
+connected device to the higher level.
+So, if you once write a device 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 device 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 device 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 /device, and you can find a sample implementation in
+/device/skeleton-directory. See below for some hints on how to
+write such a device 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 device 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 devices
+should #include <kmobileclient.h> and link to the libkmobileclient.la
+library. libkmobileclient translates all calls to DCOP calls and
+makes accessing mobile devices completely transparent to the
+application.
+
+One sample program which uses the client library is the kmobile
+kioslave. In Konqueror you might access any mobile device directly
+by giving "mobile:/" as the URL.
+
+
+
+
+
+HINTS FOR DRIVER DEVELOPERS:
+----------------------------
+- KMobile device 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 devices system-wide (creates /var/lock/LCK..<devname> files),
+  and to prevent other applications to access the same physical ports/devices
+
+- use the helper functions createDirEntry() and createFileEntry() to
+  create the right UDSEntries for listEntries(), stat(), ...
+
+- never fork() your driver !!
+