ColdSync(3p)

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.

        StartConduit() also supports the ability to run conduits without coldsync using a "run <flavor> <database> [header1=value] [header2=value] ..." format. i.e.

                dump-env run sync
                mbox-inbox run fetch InputDB=~/.palm/backup/MailDB.pdb \
                        OutputDB=~/.palm/backup/MailDB.pdb Mailbox=~/Mail/palm

        This is useful for running from "cron" or for debugging conduits. Of course, sync conduits won't be able to use SPC to communicate with a PDA.

    EndConduit([status,message])
        Cleans up after a single-flavor conduit. If defined, outputs the given status code and message to STDOUT. If left undefined, the status will be 202 and the message "Success!".

        In the case of a success code (2xx), the open database $PDB will be written to the file $HEADERS{OutputDB} if necessary. In cases where the database $PDB hasn't been modified (and $HEADERS{OutputDB} is the same as $HEADERS{InputDB}) nothing will happen.

        EndConduit returns zero on success.

    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.

        ConduitMain() also supports the ability to run conduits without coldsync using a "run <flavor> [header1=value] [header2=value] ..." format. i.e.

                dump-env run sync
                mbox-inbox run fetch InputDB=~/.palm/backup/MailDB.pdb \
                        OutputDB=~/.palm/backup/MailDB.pdb Mailbox=~/Mail/palm

        This is useful for running from "cron" or for debugging conduits. Of course, sync conduits won't be able to use SPC to communicate with a PDA.

SEE ALSO
Palm::PDB(1)

ColdSync Conduits: Specification and Hacker's Guide