ColdSync - Convenience module for writing ColdSync conduits.

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

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.

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 CWInputDB header argument, it will be read into CW$PDB. When the conduit terminates, if it is expected to write a Palm database, it will write CW$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 CW%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 CW$PREFERENCES{"mail"}{6} contains the preference item whose creator is CWmail and whose ID is 6.

StartConduit(flavor)

Initializes a single-flavor conduit. Its argument is a string specifying the flavor of the conduit, either CW"fetch", CW"dump", or CW"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 CWInputDB header was given, loads the named file into CW$PDB. If the program is run not as a conduit but as a standalone program, StartConduit() supports the CW-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 CW$PDB to the file given by CW$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 CW-config option: when this option is given, the program prints to STDOUT a set of sample configuration entries that may be appended to .coldsyncrc.

Palm::PDB(1) ColdSync Conduits: Specification and Hacker's Guide