Engine/Sync from an application developer’s perspective

General features and behaviour

p≡p Sync is a protocol family, which is meant to deliver the following features:

  • devices find each other and initiate a handshake to form a device group by exchanging messages through configured accounts
  • common information like default keys, trust, etc. are shared and kept in sync inside the group
  • a grouped device may stop syncing
  • own identities, especially accounts, may be excluded from this process

The following properties must be preserved:

  • If Sync is enabled then a device may be Sole or it may be Grouped, which means it may be member of a device group.
  • If Sync is disabled then a device is never Grouped. Disabling Sync implies leaving a device group on a Grouped device.

Managing config and API usage

Managing config if Sync is enabled or disabled

The application must sport a switch where the user can switch Sync on or off.

If Sync formerly was disabled and is enabled now the application must do the following in sequence:

  1. call disable_identity_for_sync() for all own identities of all accounts, which must not be enabled, in case a selection was done
  2. call enable_identity_for_sync() for all own identities of all accounts, which must be enabled
  3. call start_sync()

If Sync formerly was enabled and is disabled now the application must do the following:

  • call leave_device_group()

Managing config for which accounts Sync will be used

The application must support a switch where the user can decide if Sync is being used for all accounts or for a selection of accounts.

If the user is opting for a selection of accounts then the application must sport a selection list with all accounts where the user can decide which account will be enabled for sync and which will be disabled. If this is first time config then the default for each account is selected.

Selecting no account there is invalid input. At least one account must be selected to successfully enable Sync.

When selection was being done the application must execute the following for all accounts where the selection was changed:

  1. call disable_identity_for_sync() for all accounts, which must now be disabled
  2. call enable_identity_for_sync() for all accounts, which must now be enabled

Application startup

  1. have at least one account configured
  2. call myself() for all accounts
  3. in case Sync is enabled while startup the application must call start_sync(), otherwise it must not (default: enabled)

Application shutdown

  • in case Sync is enabled while shutdown the application must call stop_sync(), otherwise it must not

Adding an account

  1. call myself() for the account
  2. if the account should be enabled for Sync (default) call enable_identity_for_sync() otherwise call disable_identity_for_sync()

Engine requiring App or user interaction

Disclaimer: The concrete details of this calls depend on the Adapter implementation

There are mainly two callbacks for when the engine needs to comunicate with the app

  1. messageToSend() this commands the app to send a message as it is.
  2. notifyHandshake() this notifies the app the current sync step we are in:

    // Request show handshake dialog -> App must show a Handshake dialog and deliver result with deliverHandshakeResult // Can be used to start fast polling on App side
    // handshake process timed out -> For some reason sync could not finish
    // handshake accepted by user -> Can be ignored // Can be used to finish fast polling on app side
    // these two notifications must be evaluated by applications, which are // using a Desktop Adapter -> Other app on the system started or stoped sync
    • SYNC_NOTIFY_START = 126,
    • SYNC_NOTIFY_STOP = 127,
    // message cannot be sent, need passphrase -> App needs to request a passphrase and call config_passphrase()
    // Current status -> App can use it to show if we are part of a group or not.
    • SYNC_NOTIFY_SOLE = 254,

This callbacks are set during engine startup before calling start_sync().