The entrypoint to the Ditto SDK. More...

Public Member Functions
	Ditto (DittoIdentity identity=default, string workingDir=null)
	Initializes a new instance of the Ditto class.
string	AppId ()
	Get the Ditto application Id.
void	StartSync ()
	Starts the network transports. Ditto will connect to other devices.
void	StopSync ()
	Stops all network transports.
void	SetOfflineOnlyLicenseToken (string licenseToken)
	Activate an offline Ditto instance by setting a license token. You cannot sync with Ditto before you have activated it. The offline license token is only valid for Development, Manual, OfflinePlayground and SharedKey identities.
DittoTransportDiagnostics	TransportDiagnostics ()
	Request bulk status information about the transports. This is mostly intended for statistical or debugging purposes.
DittoTransportDiagnostics	GetTransportDiagnostics ()
	Request bulk status information about the transports. This is mostly intended for statistical or debugging purposes.
DittoPeersObserver	ObservePeers (Action< List< DittoRemotePeer > > callback)
	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. From then on it will be invoked repeatedly when Ditto devices come and go, or the active connections to them change.
void	DisableSyncWithV3 ()
	Disable sync with peers running version 3 or lower of the Ditto SDK.
void	RunGarbageCollection ()
	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 collection process in the background at optimal times.
void	UpdateTransportConfig (Action< DittoTransportConfig > configure)
	Convenience method to update the current transport config of the receiver.

Static Public Member Functions
static Task< Ditto >	OpenAsync (DittoConfig config=null)
	Asynchronously creates and returns a new Ditto instance using the provided configuration.
static Ditto	Open (DittoConfig config=null)
	Synchronously creates and returns a new Ditto instance using the provided configuration.

Protected Member Functions
override void	Dispose (bool disposing)
	Overload for types to dispose of resources, regardless of whether the type is being disposed or finalized. Note that finalization occurs on a dedicated thread.

Properties
static string	DefaultRootDirectory `[get]`
	Gets the default root directory used for Ditto data persistence.
static string	Version `[get]`
	Gets a string containing the semantic version of the Ditto SDK. Example: 4.5.0.
DittoConfig	Config `[get]`
	Gets the configuration used to initialize this Ditto instance.
bool	IsSyncActive `[get]`
	Gets a value indicating whether or not sync is active. Use `StartSync()` to activate and `StopSync()` to deactivate sync.
bool	Activated `[get]`
	Gets a value indicating whether or not the SDK has been activated.
string	DeviceName `[get, set]`
	Gets or sets a custom identifier for this peer.
ulong	SiteId `[get]`
	Gets the unique identifier of a peer in Ditto's distributed mesh network.
string	PersistenceDirectory `[get]`
	Gets the persistence directory used by Ditto to persist data.
string	AbsolutePersistenceDirectory `[get]`
	Gets the persistence directory used by Ditto to persist data, represented as an absolute path.
DittoStore	Store `[get]`
	Gets a reference to the embedded data store.
DittoSync	Sync `[get]`
	Gets the instance that provides access to the SDK's sync functionality.
DittoPresence	Presence `[get]`
	Gets a reference to the presence manager.
DittoDiskUsage	DiskUsage `[get]`
	Gets a reference to the disk usage.
string	SDKVersion `[get]`
	Gets a string identifying the version of the Ditto SDK including some metadata. See also Ditto.Version
DittoAuthenticator	Auth `[get]`
	Gets a `DittoAuthenticator` that provides access to authentication information and methods for logging on to Ditto Cloud.
DittoTransportConfig	TransportConfig `[get, set]`
	Gets or sets the transport configuration. By default, peer-to-peer transports are enabled.
DittoSmallPeerInfo	SmallPeerInfo `[get]`
	Provides access to the SDK's small peer info functionality.

Events
EventHandler< DittoTransportConditionChangedEventArgs >	DittoTransportConditionChanged
	An optional `EventHandler` delegate that can be provided to get updates about events relating to changes in network transports.
EventHandler< DittoAuthenticationRequestEventArgs >	DittoIdentityProviderAuthenticationRequest `[add, remove]`
	An optional `EventHandler` delegate that can be provided to respond to incoming authentication requests from peers who wish to join the Ditto mesh. Requires setup of signing and verification keys in the `Http` part of `TransportConfig`.

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.

Constructor & Destructor Documentation

◆ Ditto()

DittoSDK.Ditto.Ditto	(	DittoIdentity	identity = default,
		string	workingDir = null )

inline

Initializes a new instance of the Ditto class.

Phased out in 4.x — replaced by Ditto.Open(DittoConfig) and Ditto.OpenAsync(DittoConfig) factory methods. This API will be replaced by the new factory methods in v5.

Parameters

identity	Provide the identity of the entity that is interacting with Ditto.
workingDir	The directory that will be used to persist Ditto data.

Member Function Documentation

◆ AppId()

string DittoSDK.Ditto.AppId ( )

inline

Get the Ditto application Id.

Phased out in 4.x — replaced by DittoConfig.DatabaseId — now accessible via Ditto.Config. This API will be replaced by DittoConfig.DatabaseId in v5.

Returns: The Ditto application Id.

◆ DisableSyncWithV3()

void DittoSDK.Ditto.DisableSyncWithV3 ( )

inline

Disable sync with peers running version 3 or lower of the Ditto SDK.

Required for the execution of mutating DQL statements.

This setting spreads to other peers on connection. Those peers will in turn spread it further until all peers in the mesh take on the same setting. This is irreversible and will persist across restarts of the Ditto instance.

Calling this method before StartSync is recommended whenever possible. This improves performance of initial sync when this peer has never before connected to a Ditto mesh for which sync with v3 peers is disabled.

◆ Dispose()

override void DittoSDK.Ditto.Dispose ( bool disposing )

inlineprotected

Overload for types to dispose of resources, regardless of whether the type is being disposed or finalized. Note that finalization occurs on a dedicated thread.

Parameters

disposing true when invoked from an explicit Dispose() call. false when invoked from the finalizer.

◆ GetTransportDiagnostics()

DittoTransportDiagnostics DittoSDK.Ditto.GetTransportDiagnostics ( )

inline

Request bulk status information about the transports. This is mostly intended for statistical or debugging purposes.

Returns: An instance of DittoTransportDiagnostics that represents the current state of the network transports that the SDK is using.

◆ ObservePeers()

DittoPeersObserver DittoSDK.Ditto.ObservePeers ( Action< List< DittoRemotePeer > > callback )

inline

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. From then on it will be invoked repeatedly when Ditto devices come and go, or the active connections to them change.

Parameters

callback The Action that will be invoked when there is a presence update.

Returns: A DittoPeersObserver instance, which must be retained to continue receiving callback updates.

◆ Open()

Ditto DittoSDK.Ditto.Open ( DittoConfig config = null )

inlinestatic

Synchronously creates and returns a new Ditto instance using the provided configuration.

This is a blocking convenience method for initializing Ditto, intended for use in non-async environments. The method will block the calling thread until the instance is ready or an error is thrown.

Important: This API is in preview and will become the standard way to initialize Ditto instances in v5, replacing the legacy Ditto(DittoIdentity, string) constructor.

Parameters

config The configuration to initialize the new Ditto instance with. Defaults to DittoConfig.Default.

Returns: The newly created Ditto instance.

Exceptions

DittoStoreException	Thrown with `PersistenceDirectoryLocked` if the chosen persistence directory is already in use by another Ditto instance.
DittoValidationException	Thrown with `InvalidDittoConfig` if the passed in config 's contents do not meet the required validation criteria. For detailed information on the validation requirements, consult the documentation of the individual properties of DittoConfig.
DittoException	May throw other DittoExceptions for other initialization failures.

See also: OpenAsync(DittoConfig)

◆ OpenAsync()

Task< Ditto > DittoSDK.Ditto.OpenAsync ( DittoConfig config = null )

inlinestatic

Asynchronously creates and returns a new Ditto instance using the provided configuration.

Important: In Ditto version 4.x, this method is only partially async and blocks for a significant portion of the initialization process. It will become fully async starting with Ditto 5.0.

Important: This API is in preview and will become the standard way to initialize Ditto instances in v5, replacing the legacy Ditto(DittoIdentity, string) constructor.

Parameters

config The configuration to initialize the new Ditto instance with. Defaults to DittoConfig.Default.

Returns: The newly created Ditto instance.

Exceptions

DittoStoreException	Thrown with `PersistenceDirectoryLocked` if the chosen persistence directory is already in use by another Ditto instance.
DittoValidationException	Thrown with `InvalidDittoConfig` if the passed in config 's contents do not meet the required validation criteria. For detailed information on the validation requirements, consult the documentation of the individual properties of DittoConfig.
DittoException	May throw other DittoExceptions for other initialization failures.

See also: Open(DittoConfig)

◆ RunGarbageCollection()

void DittoSDK.Ditto.RunGarbageCollection ( )

inline

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 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.

◆ SetOfflineOnlyLicenseToken()

void DittoSDK.Ditto.SetOfflineOnlyLicenseToken ( string licenseToken )

inline

Activate an offline Ditto instance by setting a license token. You cannot sync with Ditto before you have activated it. The offline license token is only valid for Development, Manual, OfflinePlayground and SharedKey identities.

Parameters

licenseToken The license token to activate the Ditto instance with, which you can find on the Ditto portal (https://portal.ditto.live).

Exceptions

DittoException	Thrown if the provided license token is expired or invalid.
Exception	Thrown if you attempt to set an offline license token on an online identity.

◆ StartSync()

void DittoSDK.Ditto.StartSync ( )

inline

Starts the network transports. Ditto will connect to other devices.

By default, Ditto will enable all peer-to-peer transport types available. The default network configuration can be modified via TransportConfig

Performance of initial sync when bootstrapping a new peer can be improved by calling DisableSyncWithV3 before calling StartSync. Only do this when all peers in the mesh are known to be running Ditto v4 or higher.

Exceptions

ExpirationHandlerMissingException	Thrown if the Ditto instance was initialized with Connect set to DittoConfigConnect.Server while `ExpirationHandler` is `null`. For sync to work with server connections, Ditto requires (a) a DittoAuthenticationExpirationHandler to be set via `ditto.Auth.ExpirationHandler`, and (b) that handler to properly authenticate when requested.
DittoException	Thrown if the Ditto instance hasn't been activated by a successful call to `SetOfflineOnlyLicenseToken`.

◆ StopSync()

void DittoSDK.Ditto.StopSync ( )

inline

Stops all network transports.

You may continue to use the Ditto store locally but no data will sync to or from other devices.

◆ TransportDiagnostics()

DittoTransportDiagnostics DittoSDK.Ditto.TransportDiagnostics ( )

inline

Request bulk status information about the transports. This is mostly intended for statistical or debugging purposes.

Returns: An instance of DittoTransportDiagnostics that represents the current state of the network transports that the SDK is using.

◆ UpdateTransportConfig()

void DittoSDK.Ditto.UpdateTransportConfig ( Action< DittoTransportConfig > configure )

inline

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

Invokes the lambda expression with a copy of the current transport config which you can alter to your liking. The updated transport config is then set upon the receiver.

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

Parameters

configure A delegate that receives a copy of the current DittoTransportConfig to modify.

Property Documentation

◆ AbsolutePersistenceDirectory

string DittoSDK.Ditto.AbsolutePersistenceDirectory

get

Gets the persistence directory used by Ditto to persist data, represented as an absolute path.

The value returned by this property depends on what was specified in DittoConfig.PersistenceDirectory:

If an absolute path was provided, it is returned unchanged.
If a relative path was provided, it is resolved relative to Ditto.DefaultRootDirectory.
If null was provided, the default path is used in the format: {defaultRoot}/ditto-{database-id}, where {defaultRoot} corresponds to Ditto.DefaultRootDirectory and {database-id} is the lowercase Ditto database ID.

This property always returns a consistent, resolved absolute path for the lifetime of the Ditto instance, and it represents the actual directory being used for data persistence.

Note: "Database ID" was previously referred to as "App ID" in older versions of the SDK.

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 DittoLogger is enabled, logs may be written to this directory even after the Ditto instance has been disposed. See the DittoLogger documentation for more information.

◆ Activated

bool DittoSDK.Ditto.Activated

get

Gets a value indicating whether or not the SDK has been activated.

If false then you need to call Ditto.SetOfflineOnlyLicenseToken(string) before interacting with the SDK.

◆ Config

DittoConfig DittoSDK.Ditto.Config

get

Gets 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].

If this instance was initialized using the deprecated parameter-based APIs, the returned configuration will be an incomplete approximation, since there is no exact 1:1 mapping between the old parameters and the new DittoConfig. In this case, a warning will be logged.

Warning: Accessing this property on a Ditto instance created with the deprecated parameter-based APIs may result in a partially filled configuration. Prefer using the new DittoConfig-based initialization methods whenever possible.

Important: This API is in preview and provides a read-only property to access the configuration used during initialization of a Ditto instance. This will be the standard way to access configuration in v5.

◆ DefaultRootDirectory

string DittoSDK.Ditto.DefaultRootDirectory

staticget

Gets the default root directory used for Ditto data persistence.

On iOS, Android or MacCatalyst targets, this returns the AppDataDirectory. On other platforms, it defaults to the current working directory (Environment.CurrentDirectory).

This value is used when a relative persistence directory path (or null) is provided in the configuration.

◆ DeviceName

string DittoSDK.Ditto.DeviceName

getset

Gets or sets a custom identifier for this peer.

When using ObservePeers(), 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 DittoSync.Start() 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 DittoSync.Start() is called.

◆ PersistenceDirectory

string DittoSDK.Ditto.PersistenceDirectory

get

Gets the persistence directory used by Ditto to persist data.

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 DittoLogger is enabled, logs may be written to this directory / even after a Ditto instance was deallocated. Please refer to the / documentation of DittoLogger for more information. / [Obsolete("Please use `AbsolutePersistenceDirectory` instead.")]

◆ SiteId

ulong DittoSDK.Ditto.SiteId

get

Gets the unique identifier of a peer in Ditto's distributed mesh network.

IMPORTANT: This must be unique or the merging and conflict resolution will have unexpected behavior.

◆ TransportConfig

DittoTransportConfig DittoSDK.Ditto.TransportConfig

getset

Gets or sets the transport configuration. By default, peer-to-peer transports are enabled.

You may use this property to alter the configuration at any time; however, sync will not begin until DittoSync.Start() is called.

Important: Modifying any sub-property of the retrieved DittoTransportConfig (e.g., disabling Bluetooth via PeerToPeer.BluetoothLE.Enabled = false) will not apply the change automatically. To persist changes, you must either:

Use UpdateTransportConfig to safely apply the change immediately.
Assign a new or modified instance back to this property manually.

Public Member Functions

Static Public Member Functions

Protected Member Functions

Properties

Events

Detailed Description

Constructor & Destructor Documentation

◆ Ditto()

Member Function Documentation

◆ AppId()

◆ DisableSyncWithV3()

◆ Dispose()

◆ GetTransportDiagnostics()

◆ ObservePeers()

◆ Open()

◆ OpenAsync()

◆ RunGarbageCollection()

◆ SetOfflineOnlyLicenseToken()

◆ StartSync()

◆ StopSync()

◆ TransportDiagnostics()

◆ UpdateTransportConfig()

Property Documentation

◆ AbsolutePersistenceDirectory

◆ Activated

◆ Config

◆ DefaultRootDirectory

◆ DeviceName

◆ PersistenceDirectory

◆ SiteId

◆ TransportConfig