1 files changed, 67 insertions, 0 deletions
diff --git a/kpilot/Documentation/HOWTO-CONDUIT.txt b/kpilot/Documentation/HOWTO-CONDUIT.txt
new file mode 100644
index 000000000..7b6dccd0b
--- /dev/null
+++ b/kpilot/Documentation/HOWTO-CONDUIT.txt
@@ -0,0 +1,67 @@
+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).