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):
-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.
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.
-z option, it will run
Install conduits and install new databases after the main sync. See
above.
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.
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).
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).
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.
Certain header fields have predefined meanings and formats:
Daemon
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.
Version
Version header specifies the version of the program
identified by Daemon.
InputDB
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.
OutputDB
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.
Preference
Preference header identifies a preference being passed
to the conduit. Each Peference header is of the form
Preference: creator/ID/lengthwhere 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).
SPCPipe
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.
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:
NOP
No-op. This does nothing, neither sends nor receives any data
from the Palm, and is mainly useful as a connectivity test between the
conduit and ColdSync. The response to a NOP has 0 bytes of data.
DBINFO
Get database information. Returns a struct dlp_dbinfo,
similar to those returned by the dlpReadDBList request, except
that the SPC request returns the copy that ColdSync has already fetched,
so it does not involve extra communication with the Palm over a slow
serial connection.
DLPC
This is the most powerful SPC request. The data for a
DLPC request is a raw DLP request that will be sent to the Palm.
The response is the raw response, as received from the Palm.
There are currently four conduit flavors: Sync, Fetch, Dump, and Install.
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 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 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 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.
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:
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.
There might conceivably be multiple forms of success. In the meantime, the recommended code for a plain, ordinary success is 202.
ColdSync.pm module if no status code was provided.
InputDB file, unsupported
version of ColdSync, and so forth.
InputDB file, etc.
ColdSync.pm Perl module.
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.