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 numberPALMRS_SYNC_MODE
- sync mode (one ofkeep-local
,keep-device
, ormerge
)PALMRS_DATA_LOCAL
- path to the local data directory for this conduitPALMRS_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
- Conduit call handler
- Container (with builder API) for sync conduit requirements