
		       PilotManager Conduit API
		       ------------------------


			       OVERVIEW
			       --------

Here's a quick take on what you need to do to write a PilotManager
Conduit.  This is a very sketchy document and is designed just to give
you a basic framework of what is necessary.  PilotManager uses Perl5
with the Tk extension.  The best tutorial/documentation is to read the
modules themselves and understand how they work.  At some later date
if there's enough demand, I'll write a more sophisticated document to
cover this material.

			     REQUIREMENTS
			     ------------

Your conduit must have the following attributes:

	- Must be a Perl5 package with a unique name
	- The package filename must be of the format XXX.pm
	- The package must contain the following functions:
		- conduitInit()
		- conduitInfo()
		- conduitSync()
		- conduitQuit()
		- conduitConfigure()

When PilotManager calls your conduit, it will already be in
PilotManager's resource dir (currently ~/.pilotmgr).  At this point,
PilotManager will have created a directory with the same name as your
package, so you're expected to write only in that directory.  For
example, if your module is "SyncCM" and you want to create a file
called 'prefs', you'd create it as "SyncCM/prefs".  This is a shared
environment so please be careful not to whack some other conduit's
files. 


			      FUNCTIONS
			      ---------

sub conduitInit()

	Argument 1:	$self
			This is the instance of your object that
			PilotManager is using.
	
	PilotManager will call this function before it calls any other
	function in your module.  It will only be called once, so use
	it to read preferences, set up your initial values, etc.

sub conduitInfo()
	
	Argument 1:	$self
			This is the instance of your object that
			PilotManager is using.

	PilotManager may call this function several times to find out
	about your conduit.  You are expected to return a hash table
	containing the following keys:

		version		Your conduit's version number,
				preferably in the perl standard
				floating point form of "X.YYY" where X
				is the major number and Y is the minor
				number, padded to three digits by 0's.
				For example, if your code is major rev
				1, minor rev 4, your version is
				"1.004".

		author		The author's name	[optional]

		email		The author's email	[mandatory]

sub conduitSync()

	Argument 1:	$self
			This is the instance of your object that
			PilotManager is using.

	Argument 2:	$pilot_sock
			This is the perl file handle for the socket
			that is connected to the Pilot.

	Argument 3:	$info
			This is a pointer to a PilotUser structure
			containing sync info from the Pilot.  This
			structure contains the username, and sync
			dates. 

	PilotManager will call this function whenever the user wishes
	to sync a database that you support.  Your conduit is expected
	to open and sync any databases that you are responsible for.
	You should use the following functions to report back to 
	PilotManager:


		PilotMgr::msg(<string>) 
	
			Report major events during the sync

		PilotMgr::status(<string>,<percent>)

			Report status and minor events.  Call this often
			as it also gives the GUI a chance to update.

	If something goes wrong and you need to abort, you can always
	use Carp::croak() to bail immediately with an error code.  
	PilotManager will catch this and Do the Right Thing.

sub conduitQuit()
	
	Argument 1:	$self
			This is the instance of your object that
			PilotManager is using.

	PilotManager will call this once, before exiting.  This is an
	opportunity to clean up any tmp files, etc.

sub conduitConfigure()
	
	Argument 1:	$self
			This is the instance of your object that
			PilotManager is using.

	Argument 2:	$wm
			This is a Perl/Tk MainWindow object that you
			can use to create your configure dialog.

	PilotManager will call this whenever the user attempts to
	configure your module.  You're expected to pop up a dialog
	with widgets that the user can configure your module with.


