/usr/share/perl5/PilotMgr/docs/Conduit.api is in pilot-manager 1.107.0pre108-5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | 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.
|