Go to the first, previous, next, last section, table of contents.


ColdSync allows the user to extend its functionality by means of conduits. A conduit is a program that is run from ColdSync, and which interacts with ColdSync according to a well-defined protocol.

Conduits come in multiple flavors. ColdSync runs conduits at several points during its execution. The flavor of a conduit indicates the intended purpose of the conduit. See section Conduit Flavors.

ColdSync communicates with conduits by sending information to the conduit's standard input (see section Conduit Input), and by reading results from the conduit's standard output (see section Conduit Output). This information is mostly in human-readable text form.

A sync consists of the following phases (somewhat simplified):

  1. Initialization
    ColdSync starts up, reads its configuration file(s), and performs basic initialization.
  2. User presses HotSync button
    This indicates the beginning of the sync.
  3. Gather information
    ColdSync gathers information from the Palm, such as the list of databases.
  4. Fetch preferences
    ColdSync fetches from the Palm any preferences specified in the conduit configuration. Note that in the current implementation, ColdSync fetches all preferences listed in all conduits' configuration, even if those conduits will not be run.
  5. Run Install conduits and install new databases (before sync)
    If ColdSync was told to install new databases before the main sync (the -z option was not specified), it now examines each database in the install directory and runs its Install conduits.

    Afterwards, if any databases remain in the install directory, ColdSync uploads them to the Palm. If the upload was successful, ColdSync deletes the file from the install directory, and adds an entry for the new database to its list of databases installed on the Palm.

  6. Run Fetch conduits
    For each database on the Palm (including ones that have just been installed), ColdSync runs its Fetch conduits. Fetch conduits are expected to create or modify the databases in the backup directory. See section Fetch Conduits.
  7. Run Sync conduits (main sync)
    ColdSync runs Sync conduits for each database on the Palm. If no other conduit was specified for a given database, ColdSync defaults to running the generic conduit. As each database is synchronized, the message "Synchronizing Database" appears on the Palm. If no backup file exists, ColdSync creates one by downloading the database.

    ColdSync then checks all of the files in the backup directory: if a file does not correspond to any database on the Palm, that file is moved to the Attic directory.

  8. Run Install conduits and install new databases (after sync)
    If ColdSync was invoked with the -z option, it will run Install conduits and install new databases after the main sync. See above.
  9. Close the connection
    The message "HotSync complete" appears on the Palm. The user may remove it from the cradle.
  10. Run Dump conduits
    For each database on the Palm (including the ones that were just installed), ColdSync runs its Dump conduits. Dump conduits are expected to read the databases in the backup directory. See section Dump Conduits.
  11. Clean up
    ColdSync cleans up and terminates.

If the configuration file calls for more than one conduit of the same flavor to be run for the same database, the conduits will be run in the order in which they are listed in the configuration file.

ColdSync makes no guarantees as to the order in which different databases' conduits will be run, nor is there any guarantee that all of the conduits for one database will be run before the first conduit of another database.

Conduit Input

ColdSync passes information to conduits in three ways: as command-line arguments, in a series of headers and preferences on standard input, and through a designated special file descriptor (see section SPC).

Command-line Arguments

A conduit is invoked with two command-line arguments. The first is the string conduit. This argument will always be present when the conduit is run from ColdSync.

The second argument designates the conduit flavor: the string `fetch', for Fetch conduits, the string dump, for Dump conduits, the string `sync', for Sync conduits, or the string install for Install conduits. (see section Conduit Flavors).

Standard Input

ColdSync writes a series of headers and preference values to the conduit's standard input. Each header is a line of the form

Field: Value

Field is a string indicating a particular type of header. It may consist of upper- and lower-case letters, digits, hyphens, and underscores. The first character may only be a letter or an underscore. The length of Field may not exceed 32 characters. Fields are case-sensitive: Foo is not the same as FOO.

The field is followed by a colon, a space, the Value string, and a newline character. The entire line may not be more than 255 characters in length, including the field, but not including the terminating newline character.

Note that a single space follows the colon. Any other whitespace is part of the value. This allows a conduit to accept an all-whitespace header value (e.g., a paragraph indentation string).

Value is a string. It may not contain any newline characters. No other restrictions are placed upon its contents, although conduit writers are encouraged to use human-readable strings.

There is currently no provision for multi-line header lines, nor for encoding methods such as "Quoted-printable."

The end of the header is indicated by a blank line, i.e., two newlines in a row.

Since preference data is binary, preferences are passed to the conduit in two parts: first, a set of Preference headers specify the preference's creator, ID, and length.

Then, after the two newlines indicating the end of the headers, comes the preference data. This is simply the concatenation of the binary data for all of the preferences referred to by the Preference headers, in the order in which those headers appeared.

Predefined Headers

Certain header fields have predefined meanings and formats:

The Daemon header identifies the program that ran the conduit. ColdSync uses the string coldsync as the value.

According to the terms of the Artistic License, a person may modify ColdSync. If the modified version is incompatible with the Standard Distribution of ColdSync, it should use some string other than coldsync to identify itself.

The Version header specifies the version of the program identified by Daemon.
The InputDB header specifies the full pathname to the database file that the conduit should use as its input. This header is mandatory for Sync and Dump conduits, and is optional for Fetch and Install conduits.

The file specified by InputDB might not exist, or might not be readable by the conduit. In such cases, the conduit should fail gracefully.

The OutputDB header specifies the full pathname to the database file that the conduit should use as its output. This header is mandatory for Sync, Fetch, and Install conduits, and is optional for Dump conduits.

The file specified by OutputDB might not exist, in which case the conduit may create it. If it exists but is not writable by the conduit, the conduit should fail gracefully.

A Preference header identifies a preference being passed to the conduit. Each Peference header is of the form
Preference: creator/ID/length
where creator is the preference's four-character creator, ID is its numerical identifier (decimal), and length is the length of the preference data following the header (decimal).
The SPCPipe header specifies the number (decimal) of an open file descriptor. This file descriptor may be used for SPC communications (see section SPC).

Other headers may be passed to the conduit, so the conduit should be prepared to handle them.

If multiple InputDB or OutputDB headers are sent to a conduit, the last value sent is the authoritative one. It is an error to send more than one Daemon or Version header.

Conduit Output

A conduit may write lines to standard output. Each line should be of the form

NNN Message

where NNN is a three-digit status code (see section Status Codes), and Message is a human-readable string. A single space separates the status code from the message.

Each line may be up to 255 characters in length, counting the status code, but not counting the terminating newline. There is currently no provision for multi-line messages.

The three-digit status code indicates some condition that the conduit wishes to report to ColdSync, such as successful or unsuccessful termination, a warning, or an informational progress report. The meanings of various status codes are defined in section Status Codes.

ColdSync does not attempt to parse the message string. It is intended solely for human readers.

A conduit may print any number of lines. The status code of the last line printed by the conduit before it exits indicates the final exit status of the conduit, i.e., success or failure.

Only 2yz, 4yz, and 5yz status codes may be used for the exit status.


The Serialized Procedure Call (SPC) is a protocol that allows a Sync conduit to communicate with the Palm. A Sync conduit is passed an SPCPipe header that gives the number of a file descriptor over which it can communicate via SPC (see section Predefined Headers).

SPC is similar in spirit to RPC (Remote Procedure Call): the conduit sends an SPC request over the SPC file descriptor, and receives a response.

SPC requests and responses have the same form:

	unsigned short op;
	unsigned short status;
	unsigned long len;
	// len bytes of data

where op is an opcode indicating which operation to perform; status indicates whether the operation was successful or not; len gives the length of the data following the header.

Supported values for op are given by the SPCOP_* constants in `spc.h' in the ColdSync distribution. For known values for status, see the SPCERR_* constants in that file.

All numeric values are given in network byte order. A short is 16 bits long; a long is 32 bits long.

status is ignored in a request packet.

In a response packet, op is the opcode of the request.

The following SPC operations are currently defined:

Conduit Flavors

There are currently four conduit flavors: Sync, Fetch, Dump, and Install.

Sync conduits

Sync conduits run during the main sync. The intended purpose of a Sync conduit is to ensure that a database on the Palm and its backup on the desktop both contain identical, up-to-date information. The generic conduit is a special instance of a Sync conduit.

Sync conduits have the unique property that they run while ColdSync is connected to the Palm, and so may communicate with it by using the SPC protocol (see section SPC).

Fetch Conduits

Fetch conduits run before the main sync. The purpose of a Fetch conduit is to create or modify the backup copy of a database before ColdSync compares it to the copy on the Palm. The conduit may, for instance, add new records to be uploaded to the Palm.

Dump Conduits

Dump conduits run after the main sync. The purpose of a Dump conduit is to examine a database in the backup directory after it has been synchronized with the copy on the Palm. Usually, a Dump conduit will write the contents of the database in some other format, e.g., that of some other application.

In most cases, a Dump conduit will only need to read its database. If necessary, however, it may modify the database. For instance, a Dump conduit for the Palm Mail application may send out every message in the Outbox, then delete it from the database.

Install conduits

Install conduits run just before new databases are uploaded to the Palm, which may happen either before or after the main sync. The purpose of an Install conduit is to examine a database that is about to be installed, and possibly delete or modify it, or create a new one.

Status Codes

The status codes that a conduit sends to ColdSync should be of the form of a three-digit decimal integer xyz.

The first digit, x, indicates a general message class (success, failure, informational message, etc).

The second digit, y, represents a category within the message class (file error, system error, etc.)

The third digit, z, indicates a specific condition (out of memory, no such file, etc.)

The precise meaning of most status codes is still undefined. Only the following classes have been defined:

Debugging messages. These will normally not be shown to the user. The precise circumstances under which they will be shown to the user have yet to be defined.
Informational messages. These will normally be shown to the user, but do not indicate that anything is wrong.

In future versions of ColdSync, certain 1yz codes may acquire standard meanings, and their associated text strings will have a recommended format. This should allow real-time updates of the form "NN% complete" that can be displayed on the user's desktop.

Successful completion.

There might conceivably be multiple forms of success. In the meantime, the recommended code for a plain, ordinary success is 202.

Warning. The 3yz status codes indicate that something is wrong, but that the conduit has managed to recover.
Unspecified warning. Indicates that something odd has occurred, but does not specify what. This is the default warning printed by the ColdSync.pm module if no status code was provided.
ColdSync (caller) error. A 4yz code indicates that the conduit has failed because it was given improper input, e.g., invalid or missing command-line arguments, nonexistent InputDB file, unsupported version of ColdSync, and so forth.
Unspecified Error.
Lost connection to Palm.
Conduit error. A 5yz code indicates that the conduit should have been able to perform its function, but couldn't. Reasons include running out of memory, segmentation violation, inability to parse an apparently-correct InputDB file, etc.
Unspecified error. Indicates that the conduit was not able to terminate for some reason other than improper input, but does not specify the cause. This is the default error code used by the ColdSync.pm Perl module.
These error codes are currently undefined, but may be used in future versions. Until then, they should not be used.

The last status code sent by the conduit before exiting gives the exit status of the conduit as a whole. That is, if a conduit exits successfully, the last thing it prints should be a 2yz status code.

Only 2yz, 4yz, and 5yz status codes may be used for the final exit status.

Go to the first, previous, next, last section, table of contents.