ColdSync

ColdSync(3pm)         User Contributed Perl Documentation        ColdSync(3pm)



NAME
       ColdSync - Convenience module for writing ColdSync conduits.

SYNOPSIS
       Single-flavor conduits:

           use ColdSync;

           StartConduit(<flavor>);

           # Body of conduit

           EndConduit;

       Multi-flavor conduits:

           use ColdSync;

           ConduitMain(
               "dump"          => \&doDump,
               "fetch"         => \&doFetch,
               "sync"          => \&doSync,
               "install"       => \&doInstall,
               );

           sub doDump...
           sub doFetch...

DESCRIPTION
       The ColdSync module provides helper functions for writing ColdSync
       conduits. This manual page does not describe conduits or how they work;
       for this, the reader is referred to ColdSync Conduits: Specification
       and Hacker's Guide.

       The functions in this module support both Fetch, Dump, and Sync
       conduits, and perform a certain amount of sanity-checking on the
       conduit's input.

VARIABLES
       The following variables are exported to the caller by default:

       $PDB
         Holds a reference to a Palm::PDB object containing the database being
         synchronized. If the conduit was passed an "InputDB" header argument,
         it will be read into $PDB. When the conduit terminates, if it is
         expected to write a Palm database, it will write $PDB.

       %HEADERS
         Holds the headers passed to the conduit on STDIN. Duplicate headers
         are not supported. If a conduit is passed multiple headers with the
         same label, only the last one is recorded in %HEADERS.

       @HEADERS
         Holds the list of header lines passed in on STDIN, in the order in
         which they were seen. This can be useful if your conduit allows
         multiple headers, or if the order in which the headers were received
         matters.

       %PREFERENCES
         Holds the preferences passed on STDIN. The keys of this hash are the
         creators of the preference items. Their values, in turn, are
         references to hashes whose key are the IDs, and whose values are the
         raw preference item.

         Thus $PREFERENCES{"mail"}{6} contains the preference item whose
         creator is "mail" and whose ID is 6.

FUNCTIONS
         StartConduit(flavor)
           Initializes a single-flavor conduit. Its argument is a string
           specifying the flavor of the conduit, either "fetch", "dump", or
           "sync".

           StartConduit() reads and checks the conduit's command line
           arguments, reads the headers given on STDIN, and makes sure that
           all of the mandatory headers for the flavor in question are
           present. If an "InputDB" header was given, loads the named file
           into $PDB.

           If the program is run not as a conduit but as a standalone program,
           StartConduit() supports the "-config" option: when this option is
           given, the program prints to STDOUT a sample configuration entry
           that may be appended to .coldsyncrc.

         EndConduit()
           Cleans up after a single-flavor conduit. For Fetch and Sync
           conduits, writes $PDB to the file given by $HEADERS{OutputDB}. If
           everything went well, exits with status 0.

           Dump conduits are not expected to write a Palm database, so
           EndConduit() does not do so. Any Dump conduit that wishes to write
           a database must do so explicitly.

         ConduitMain(flavor => \&function, ...)
           Runs a multi-flavor conduit. Its arguments are a set of tuples of
           the form

                   "fetch" => \&myFetchFunc,

           specifying the function to call for each supported flavor. The
           function reference on the right-hand side may be any code
           reference, although in practice it is only practical to have
           references to functions.

           ConduitMain() performs the same initialization as StartConduit():
           it checks the command-line arguments, reads the headers from STDIN,
           and makes sure that the flavor is one of those given in the
           arguments, and that all of the mandatory headers were given.

           It then calls the flavor-specific function given in the arguments,
           and finally cleans up in the same way as EndConduit().

           If the program is run not as a conduit but as a standalone program,
           ConduitMain() supports the "-config" option: when this option is
           given, the program prints to STDOUT a set of sample configuration
           entries that may be appended to .coldsyncrc.

SEE ALSO
       Palm::PDB(1)

       ColdSync Conduits: Specification and Hacker's Guide



perl v5.8.7                       2002-11-13                     ColdSync(3pm)