The entrypoint to the Ditto SDK. More...

Public Member Functions
	Ditto (Ditto const &other)=delete

	Ditto (Ditto &&other) noexcept

Ditto &	operator= (Ditto const &other)=delete

Ditto &	operator= (Ditto &&other) noexcept=delete

std::shared_ptr< Authenticator >	get_auth () const
	Provides access to authentication information and methods for logging on to Ditto Cloud.

Store &	get_store () const
	Provides access to the SDK's store functionality.

SmallPeerInfo &	get_small_peer_info () const
	Provides access to the SDK's Small Peer Info functionality.

Sync &	get_sync () const
	Provides access to the SDK's sync functionality.

Presence &	get_presence () const
	Provides access to the SDK's presence functionality.

DiskUsage &	get_disk_usage () const
	Provides access to the SDK's disk usage.

TransportConfig	get_transport_config () const
	Returns the current transport config.

bool	get_is_activated () const
	Returns a flag indicating whether or not the Ditto instance has been activated by a successful call to set_offline_only_license_token.

void	set_offline_only_license_token (std::string license_token)
	Activate an offline Ditto instance by setting a license token. You cannot initiate sync on an offline (OfflinePlayground, Manual or SharedKey) Ditto instance before you have activated it.

void	set_device_name (std::string const &name)
	Set a custom identifier for the current device.

void	set_transport_config (TransportConfig config)
	Assign a new transports configuration.

void	update_transport_config (std::function< void(TransportConfig &config)> lambda)
	Convenience method to update the current transport config of the receiver.

void	run_garbage_collection () const
	Removes all sync metadata for any remote peers which aren't currently connected.

DittoConfig	get_config () const
	Returns the configuration used to initialize this `Ditto` instance.

std::string	get_persistence_directory () const
	The persistence directory used by Ditto to persist data.

std::string	get_absolute_persistence_directory () const
	The absolute path to the persistence directory used by Ditto to persist data.

PresenceObserver	observe_peers (PresenceCallback cb)
	Request information about Ditto peers in range of this device.

Static Public Member Functions
static std::shared_ptr< Ditto >	open (DittoConfig config=DittoConfig::default_config())
	Create a new Ditto instance.

static std::future< std::shared_ptr< Ditto > >	open_async (DittoConfig config=DittoConfig::default_config())
	Create a new Ditto instance asynchronously.

static std::string	get_version ()
	Returns a string containing the semantic version of the Ditto SDK.

static std::string	default_root_directory ()
	Returns the default root directory where Ditto stores its data.

static bool	get_logging_enabled ()
	Gets whether or not logging is enabled for Ditto.

static void	set_logging_enabled (bool enabled)
	Sets whether or not logging is enabled for Ditto.

static LogLevel	get_minimum_log_level ()
	Gets the minimum log level at which logs will be emitted for Ditto.

static void	set_minimum_log_level (LogLevel log_level)
	Sets the minimum log level at which logs should be emitted for Ditto.

Detailed Description

The entrypoint to the Ditto SDK.

For a Ditto instance to continue to connect to other devices it must be kept in scope.

Member Function Documentation

◆ default_root_directory()

static std::string ditto::Ditto::default_root_directory ( )

static

Returns the default root directory where Ditto stores its data.

This is the platform-specific default location used when no persistence directory is specified in the configuration:

Linux/macOS: $HOME/Documents, or $TMPDIR if HOME is not set
Windows: LOCALAPPDATA%\\Ditto\\
Android: Context's filesDir

On Android, a JNIEnv pointer and application context must be passed as arguments to this function.

Returns: The absolute path to the default root directory.

See also: DittoConfig::persistence_directory; get_absolute_persistence_directory()

◆ get_absolute_persistence_directory()

std::string ditto::Ditto::get_absolute_persistence_directory ( ) const

The absolute path to the persistence directory used by Ditto to persist data.

This method returns the final, resolved absolute file path where Ditto stores its data. The value depends on what was provided in DittoConfig::persistence_directory:

If an absolute path was provided, it returns that path unchanged
If a relative path was provided, it returns the path resolved relative to a platform-specific root directory
If no path (empty string) was provided, it returns a default path using the database ID within a platform-specific root directory

Returns: The absolute file path of the persistence directory.

Note

Platform-specific root directories:

macOS: HOME%/Documents/
Linux: HOME%/Documents/
Windows: LOCALAPPDATA%\\Ditto\\

It is not recommended to directly read from or write to this directory as its structure and contents are managed by Ditto and may change in future versions.

When Logger::set_logging_enabled(), logs may be written to this directory even after a Ditto instance has been deallocated. Please refer to the documentation of Log for more information.

See also: DittoConfig::persistence_directory

◆ get_auth()

std::shared_ptr< Authenticator > ditto::Ditto::get_auth ( ) const

Provides access to authentication information and methods for logging on to Ditto Cloud.

Attention: This function returns nullptr if the Ditto instance is not configured with an authentication mechanism.

Returns: a shared pointer to an Authenticator, or nullptr.

◆ get_config()

DittoConfig ditto::Ditto::get_config ( ) const

Returns the configuration used to initialize this Ditto instance.

Note: Sensitive data such as passphrases and private keys are redacted from the returned configuration and replaced with the string [REDACTED].

◆ get_disk_usage()

DiskUsage & ditto::Ditto::get_disk_usage ( ) const

Provides access to the SDK's disk usage.

Returns: a DiskUsage object.

◆ get_is_activated()

bool ditto::Ditto::get_is_activated ( ) const

Returns a flag indicating whether or not the Ditto instance has been activated by a successful call to set_offline_only_license_token.

Note that this is only really relevant for Ditto instances that are using an "offline" identity. When using any online-based identities this will always return true.

Returns: a flag indicating whether or not the Ditto instance has been activated.

◆ get_logging_enabled()

static bool ditto::Ditto::get_logging_enabled ( )

static

Gets whether or not logging is enabled for Ditto.

Returns: a bool representing whether or not logging is enabled for Ditto.

◆ get_minimum_log_level()

static LogLevel ditto::Ditto::get_minimum_log_level ( )

static

Gets the minimum log level at which logs will be emitted for Ditto.

Returns: the minimum log level at which logs will be emitted for Ditto.

◆ get_persistence_directory()

std::string ditto::Ditto::get_persistence_directory ( ) const

The persistence directory used by Ditto to persist data.

Returns: its path.

It is not recommended to directly read or write to this directory as its structure and contents are managed by Ditto and may change in future versions.

When Logger::set_logging_enabled(), logs may be written to this directory even after a Ditto instance was deallocated. Please refer to the documentation of Log for more information.

◆ get_presence()

Presence & ditto::Ditto::get_presence ( ) const

Provides access to the SDK's presence functionality.

Returns: a Presence object.

◆ get_small_peer_info()

SmallPeerInfo & ditto::Ditto::get_small_peer_info ( ) const

Provides access to the SDK's Small Peer Info functionality.

Returns: a SmallPeerInfo object.

◆ get_store()

Store & ditto::Ditto::get_store ( ) const

Provides access to the SDK's store functionality.

Returns: a Store object.

◆ get_sync()

Sync & ditto::Ditto::get_sync ( ) const

Provides access to the SDK's sync functionality.

Returns: a Sync object.

◆ get_transport_config()

TransportConfig ditto::Ditto::get_transport_config ( ) const

Returns the current transport config.

Returns: the current transport config.

◆ get_version()

static std::string ditto::Ditto::get_version ( )

static

Returns a string containing the semantic version of the Ditto SDK.

Example: "5.1.2"

Returns: a string identifying the version of the Ditto SDK.

◆ observe_peers()

PresenceObserver ditto::Ditto::observe_peers ( PresenceCallback cb )

Request information about Ditto peers in range of this device.

This method returns an observer which should be held as long as updates are required. A newly registered observer will have a peers update delivered to it immediately. Then it will be invoked repeatedly when Ditto devices come and go, or the active connections to them change.

Parameters

cb

Returns: PresenceObserver

◆ open()

static std::shared_ptr< Ditto > ditto::Ditto::open ( DittoConfig config = DittoConfig::default_config() )

static

Create a new Ditto instance.

Returns: a reference-counted pointer to a Ditto instance

◆ open_async()

static std::future< std::shared_ptr< Ditto > > ditto::Ditto::open_async ( DittoConfig config = DittoConfig::default_config() )

static

Create a new Ditto instance asynchronously.

Starts initializing a Ditto instance in another thread, without blocking. The caller can use the returned future to wait for or poll for the result of the operation.

Returns: a future that will eventually hold a reference-counted pointer to a Ditto instance or an exception.

◆ run_garbage_collection()

void ditto::Ditto::run_garbage_collection ( ) const

Removes all sync metadata for any remote peers which aren't currently connected.

This method shouldn't usually be called. Manually running garbage collection often will result in slower sync times. Ditto automatically runs a garbage a collection process in the background at optimal times.

Manually running garbage collection is typically only useful during testing if large amounts of data are being generated. Alternatively, if an entire data set is to be evicted and it's clear that maintaining this metadata isn't necessary, then garbage collection could be run after evicting the old data.

◆ set_device_name()

void ditto::Ditto::set_device_name ( std::string const & name )

Set a custom identifier for the current device.

When using observe_peers(), each remote peer is represented by a short UTF-8 “device name”. By default this will be a truncated version of the device’s hostname.

Changes to this property after start_sync() was called will only take effect after the next restart of sync. The value does not need to be unique among peers. Device names longer than 24 bytes will be truncated once start_sync() is called.

◆ set_logging_enabled()

static void ditto::Ditto::set_logging_enabled ( bool enabled )

static

Sets whether or not logging is enabled for Ditto.

Parameters

[in] enabled a bool representing whether or not logging is enabled for Ditto.

◆ set_minimum_log_level()

static void ditto::Ditto::set_minimum_log_level ( LogLevel log_level )

static

Sets the minimum log level at which logs should be emitted for Ditto.

Parameters

[in] log_level the minimum log level at which logs should be emitted for Ditto.

◆ set_offline_only_license_token()

void ditto::Ditto::set_offline_only_license_token ( std::string license_token )

Activate an offline Ditto instance by setting a license token. You cannot initiate sync on an offline (OfflinePlayground, Manual or SharedKey) Ditto instance before you have activated it.

Parameters

[in] license_token the license token to activate the Ditto instance with, which you can find on the Ditto portal (https://portal.ditto.live).

◆ set_transport_config()

void ditto::Ditto::set_transport_config ( TransportConfig config )

Assign a new transports configuration.

By default peer-to-peer transports (Bluetooth and WiFi, where available) are enabled.

You may use this method to alter the configuration at any time. Sync will not begin until start_sync is called.

◆ update_transport_config()

void ditto::Ditto::update_transport_config ( std::function< void(TransportConfig &config)> lambda )

Convenience method to update the current transport config of the receiver.

Invokes the block with a mutable copy of the current transport config which you can alter to your liking. The updated transport config is then set on the receiver.

You may use this method to alter the configuration at any time. Sync will not begin until start_sync is invoked.

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ default_root_directory()

◆ get_absolute_persistence_directory()

◆ get_auth()

◆ get_config()

◆ get_disk_usage()

◆ get_is_activated()

◆ get_logging_enabled()

◆ get_minimum_log_level()

◆ get_persistence_directory()

◆ get_presence()

◆ get_small_peer_info()

◆ get_store()

◆ get_sync()

◆ get_transport_config()

◆ get_version()

◆ observe_peers()

◆ open()

◆ open_async()

◆ run_garbage_collection()

◆ set_device_name()

◆ set_logging_enabled()

◆ set_minimum_log_level()

◆ set_offline_only_license_token()

◆ set_transport_config()

◆ update_transport_config()