ColdSync(3)

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: 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. 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. 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. 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
    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. 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. 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