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 accounts, which must not be enabled, in case a selection was done
  2. call enable_identity_for_sync() for 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()