By default, ColdSync is simply a fancy way of keeping a backup of what's on your Palm. This is all well and good, but what you'd really like is for your Palm to share its information with the other tools you have on your desktop.
That's where conduits come in. A conduit is an external program that ColdSync runs at certain times; you can use a conduit to extend ColdSync's behavior.
ColdSync is a generalist: it doesn't know a Calendar from a MineSweeper, so it has to treat all applications and their data in a fairly generic manner. Conduits, then, are specialists: they usually know all about one particular type of application and nothing else. This allows them to do the Right Thing for that particular application.
Since Palms don't have disks, everything has to be in memory. Consequently, PalmOS doesn't distinguish between RAM and files, the way other operating systems do. Instead, everything is a database.
There are two types of database: record databases and resource databases.
Record databases consist, naturally, of records. These are the databases that hold all of your information. The "AddressDB" database, for instance, has one record for each address in the Address Book application.
Resource databases are a bit more organized: each entry has a four-letter type, and a numerical identifier. Most resource databases are applications, containing one or more `code' entries, perhaps a few `Tbmp' (bitmap image) entries, and so forth. The types are documented strings that indicate what the resource is: `code' resources contain executable code, `Tbmp' resources are always bitmap images, and so forth. The numerical identifiers serve to tell resources of the same type apart.
Not coincidentally, resource databases are very similar to the resource fork in MacOS files.
Note that, for technical reasons, resource datatabases do not lend themselves well to syncing, and ColdSync pretty much ignores them.
Each database also has a four-letter type and a four-letter creator. Each PalmOS application has a unique creator string. Every database that it creates has the the same creator string as the application. For example, the built-in Datebook application has the creator `date'. The record database that contains the Datebook entries also has the creator `date'.
An application can potentially create several databases to
represent different kinds of data. The built-in To Do application
creates three separate record databases: `ExpenseDB', with creator
exps and type DATA; `CitiesDB', with creator
exps and type city; `VendorsDB', with creator
exps and type vend. All of these databases have the same
creator field as the application that created them, but have different
types, since they contain different kinds of information.
Since each conduit typically handles only one specific kind of database, you have to tell ColdSync what it is. For instance, to run the `kab-fetch' conduit on databases with creator `addr' and type `DATA', you would add the following to your `.coldsyncrc' file:
conduit fetch {
path: "/usr/local/libexec/coldsync/kab-fetch";
type: addr/DATA;
}
An asterisk in a creator or type specification acts as a wildcard:
type: addr/*;
the conduit will be run for every database with creator `addr', regardless of type. Likewise:
type: */DATA;
the conduit will be run for every database with type `DATA', regardless of creator (though this isn't usually very useful). Finally, you can specify wildcards for both the creator and type:
type: */*;
In this case, the conduit will be run for every database.
ColdSync defines several flavors of conduits. Each flavor performs a different function and is designed for a different purpose. Currently, four flavors are implemented.
Sync conduits implement the synchronization between a database on the Palm and its backup copy on the desktop, what is referred to here as the main sync.
The generic default conduit is a Sync conduit. It reads records from the Palm, compares them to what's on the desktop, and uploads or downloads records as necessary to ensure that both the Palm and the desktop have identical, up-to-date data.
Since Sync conduits can talk directly to the Palm, they are the most powerful, but also the most complex type of conduit. In the most common case, where all you want to do is synchronize data between the Palm and a file or database, it is simpler to write a Fetch conduit and a Dump conduit. In some cases, however, this is not possible: if you want to set the time on the Palm, your conduit needs to do so while the Palm is connected. For this, you would need to use a Sync conduit.
Fetch conduits run before the main sync. The idea is that a Fetch conduit will modify its database before ColdSync compares it to the version on the Palm. For instance, a conduit might read a list of scheduled meetings from `/usr/local/libdata/meetings' and make sure that they're all in the Address Book database in your backup directory. Then ColdSync wil make sure that any changes to the meeting list will be reflected on your Palm.
To specify a Fetch conduit in your `.coldsyncrc', use
fetch or pre-fetch as the flavor argument to
conduit, e.g.:
conduit fetch {
path: "/usr/local/libexec/coldsync/get-meetings";
type: date/DATA;
}
If you specify several conduits of the same flavor for the same database, they will be run one at a time, in the order in which they appear in `.coldsyncrc'. This allows you to chain the effects of several conduits. Bear in mind, however, that they may interfere with each other
Dump conduits run after the main sync. The intended purpose of a Dump conduit is to read its database after ColdSync is done with it, and copy its contents to some other file, in some other format. For instance, if you have made changes to your address list on the Palm, ColdSync will make sure that the backup copy in your home directory contains the same information as the Address Book database on the Palm. After that's done, a conduit can export this list in your favorite address book application's format.
To specify a Dump conduit in your `.coldsyncrc', use
dump or post-dump as the flavor argument to
conduit, e.g.:
conduit dump {
path: "/usr/local/libexec/coldsync/save-meetings";
type: date/DATA;
}
If you only have a Fetch conduit defined for a database, it can implement "Desktop overwrites handheld" syncing, where the master copy is kept on the desktop machine, and any changes made on the Palm are lost.
Conversely, if you only have a Dump conduit defined for a database, it can implement "Handheld overwrites desktop" syncing, where the master copy is kept on the Palm, and any changes made on the desktop machine are lost.
If you have both a Fetch and a Dump conduit defined for a database, they can implement two-way syncing, where changes made on the desktop are propagated to the Palm and vice versa. Since the logic of syncing can get rather hairy, especially in difficult cases, it's easier to write two simple conduits, a Fetch and a Dump, than it is to write a single conduit that does a two-way sync.
Install conduits provide a hook for manipulating databases before they're installed. In the installation phase, ColdSync looks for databases in the install directory (`~/.palm/install' by default) and runs any applicable Install conduits on them. After that, it installs any remaining files in the install directory.
If you don't like the built-in Datebook application, but people give you databases in this format, you could use an Install conduit to convert them to your favorite format. Or, depending on how bleak the future becomes, you may find it necessary to have an Install conduit check new databases for viruses, and delete them if they're infected.
The Palm has two special databases, "Saved Preferences" and "Unsaved Preferences," that contain preferences. Preferences are the PalmOS equivalent of dot files: they are neither applications nor data, but rather user preferences that affect how an application runs. The signature for outgoing mail in the Mail application is a preference. So is the "Owned by" text you can set in the Prefs application.
ColdSync conduits can request to be given the value of a preference and act accordingly. For instance, a mail conduit might request the signature preference and append it to outgoing messages.
There are two types of preferences: saved and unsaved. I have no idea what the difference is between these two types. Perhaps saved preferences are those that have found God.
Go to the first, previous, next, last section, table of contents.