One of the greatest assets of the Palm Pilot is its ability to
interconnect with other applications.  KPilot supports this capabilty
through conduits.  A conduit is a small shared library that is loaded by
the daemon during the hot sync.  The conduit translates between the Palm
Pilot and the application you're syncing with.

*** How it works

KPilot is divided into three major components: the GUI, the
syncing daemon, and the conduits.  The GUI part is actually irrelevant
for the operation of the daemon, although it _is_ required for the
configuration dialog (and possibly viewing databases). In theory
you could run the daemon on a box without even starting X, although
that is difficult (in particular, how would you do conflict resolution?).

The daemon sits around and polls the configured device every second or
so (there are devices where this should be more often, I think). Once
data arrives (and the device exists, consider hotplug with USB), the
daemon enters sync mode, and constructs a queue of SyncActions to perform.
These vary from checking the Pilot's username to performing full backups
to -- whatever sync actions the conduits provide. This means that during
a sync the shared library containing a conduit is loaded, a factory
function is called to produce an Action, this action is run, and the
library unloaded.

*** How the conduits work

The conduits can actually be divided into two parts: the configuration
widget, and the Action. Both are produced by a factory function in
the shared library. The conduits have only one really interesting method
that they must override, and that is exec(). When this is called the 
conduit is already set up with a socket descriptor and the conduit should
quickly do its thing. In particular, conduits can't just sleep(45) and
continue, since the connection with the Pilot will time out.

*** Write your very own conduit

Writing a conduit is actually rather easy.  The conduit class
should inherit from ConduitAction and override the exec() method
(which actually comes from SyncAction).


*** Debugging things

lib/options.h contains two defines that are really important for
debugging. These are

	// #define DEBUG                        (1)
	// #define DEBUG_CERR                   (1)

Uncommenting DEBUG will enable most of the debug information in
KPilot. Uncommenting DEBUG_CERR will make debug output go direct
to stderr (cerr) instead of through kdDebug. If in addition, you
pass --debug N (say, N=1 or N=4) to KPilot or the daemon when you
start them, they will print call traces (that's what FUNCTIONSETUP
does, which you will see at the beginning of every function).

Another useful tool is kpilotTest, which is in kpilot/kpilot. It
is an uninstalled binary, which behaves like the daemon with a
log window and which will run a single conduit. Something like:

	kpilotTest -p /dev/ucom0 \		# port
		-E conduit_knotes \		# .desktop file
		-T				# _really_ run

use kpilotTest -L to list the installed conduits and their
desktop files (look at the "In ..." lines).