Module palmrs_sync::conduit

source ·
Expand description

Sync conduit handling

Conduit specification

Conduits are implemented as external executables, which are called at sync time to do one of three things:

  • Replace the device’s copy of the data with the local copy of the data
  • Replace the local copy of the data with the data from the device
  • Merge the local copy of the data with the device’s copy of the data

The sync mode, along with other conduit data, is passed in the form of environment variables to the conduit process.

Environment variables

Conduits are always called with the following variables set in their environment:

  • PALMRS_SYNC_VERSION - palmrs-sync version number
  • PALMRS_SYNC_MODE - sync mode (one of keep-local, keep-device, or merge)
  • PALMRS_DATA_LOCAL - path to the local data directory for this conduit
  • PALMRS_DATA_DEVICE - path to a directory containing the entire set of Palm OS database files pulled from the device at the beginning of the sync process

In addition, conduits are called with a parsed version of their conduit-specific configuration, pulled from the palm.rs configuration for the specific device that is being synced, in their environment. The names of all of these environment variables are prefixed, and that prefix is passed to the conduit in the PALMRS_CONFIG_PREFIX environment variable.

For example, a test conduit could be called with the following environment:

PALMRS_SYNC_VERSION="0.1.0-dev.1"
PALMRS_SYNC_MODE="keep-device"
PALMRS_DATA_LOCAL="/home/user/Documents/palm.rs/conduits/conduit-test"
PALMRS_DATA_DEVICE="/tmp/palmrs-device-data.27b862fa.tmp"
PALMRS_CONFIG_PREFIX="CONDUIT_TEST__"
CONDUIT_TEST__HELLO_WORLD="Hello, world!"

Local data

Conduits are free to store whatever data they would like, in whatever format they would like, in their local data directory (the path to which is specified in the PALMRS_DATA_LOCAL environment variable passed to the conduit).

It is recommended, but not required, that conduits store their data in a format that is easily editable by a human - either directly with a text editor, or by using already available tools.

Device data

All of the Palm OS database files that have been synced from the device, regardless of whether or not the specific conduit needs them, will be available in the directory specified by the PALMRS_DATA_DEVICE environment variable.

The data available in that directory may not be the result of a “full” (i.e. “backup”) sync with the device - in that case, the partial data from the current sync will be overlaid on top of the data from the last “full” sync.

When the conduit is operating in keep-local or merge modes, any data written back to any of the databases in the PALMRS_DATA_DEVICE directory (or, any new database files that are added to that directory) will be synced back to the device. When the conduit is operating in keep-device mode, the conduit MAY NOT make changes to the databases in that directory.

Structs