Ditto  1.1.1
Public Member Functions | Properties | List of all members
DittoSDK.Ditto Class Reference

The entrypoint to the Ditto SDK. More...

Public Member Functions

unsafe Ditto (DittoIdentity identity=default, string workingDir="ditto")
 Initializes a new instance of the Ditto class. More...
 
void StartSync ()
 Starts the network transports. Ditto will connect to other devices. More...
 
unsafe void TryStartSync ()
 Starts the network transports. Ditto will connect to other devices. More...
 
void StopSync ()
 Stops all network transports. More...
 
void SetTransportConfig (DittoTransportConfig config)
 Assign a new transports configuration. By default peer-to-peer transports are enabled. More...
 
unsafe void SetLicenseToken (string licenseToken)
 Activate a Ditto instance by setting a license token. You cannot sync with Ditto before you have activated it. More...
 
unsafe void SetAccessLicense (string license)
 Activate a Ditto instance by setting a license token. You cannot sync with Ditto before you have activated it. More...
 
DittoTransportDiagnostics TransportDiagnostics ()
 Request bulk status information about the transports. This is mostly intended for statistical or debugging purposes. More...
 
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. More...
 
unsafe 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 a collection process in the background at optimal times. More...
 

Properties

bool IsSyncActive = false [get]
 A flag indicating whether or not sync is active. Use TryStartSync() to activate and StopSync() to deactivate sync. More...
 
bool Activated [get]
 Gets a value indicating whether or not the SDK has been activated. More...
 
string DeviceName [get, set]
 Gets or sets a custom identifier for the current device. More...
 
unsafe ulong SiteId [get]
 Gets the unique identifier of a peer in Ditto's distributed mesh network. More...
 
DittoStore Store [get]
 Gets a reference to the embedded data store. More...
 
unsafe string SDKVersion [get]
 Gets a string identifying the version of the Ditto SDK. More...
 
DittoAuthenticator Authenticator [get]
 Gets a DittoAuthenticator that provides access to authentication information and methods for logging on to Ditto Cloud. More...
 
DittoAuthenticator Auth [get]
 Gets a DittoAuthenticator that provides access to authentication information and methods for logging on to Ditto Cloud. More...
 

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()

unsafe DittoSDK.Ditto.Ditto ( DittoIdentity  identity = default,
string  workingDir = "ditto" 
)
inline

Initializes a new instance of the Ditto class.

Parameters
identityProvide the identity of the entity that is interacting with Ditto.
workingDirThe directory that will be used to persist Ditto data.

Member Function Documentation

◆ 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
callbackThe Action that will be invoked when there is a presence update.
Returns
A DittoPeersObserver instance, which must be retained to continue receiving callback updates.

◆ RunGarbageCollection()

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

◆ SetAccessLicense()

unsafe void DittoSDK.Ditto.SetAccessLicense ( string  license)
inline

Activate a Ditto instance by setting a license token. You cannot sync with Ditto before you have activated it.

Parameters
licenseThe license token to activate the Ditto instance with, which you can find on the Ditto portal (https://portal.ditto.live).
Exceptions
DittoExceptionThrown if the provided license token is expired or invalid.

◆ SetLicenseToken()

unsafe void DittoSDK.Ditto.SetLicenseToken ( string  licenseToken)
inline

Activate a Ditto instance by setting a license token. You cannot sync with Ditto before you have activated it.

Parameters
licenseTokenThe license token to activate the Ditto instance with, which you can find on the Ditto portal (https://portal.ditto.live).
Exceptions
DittoExceptionThrown if the provided license token is expired or invalid.

◆ SetTransportConfig()

void DittoSDK.Ditto.SetTransportConfig ( DittoTransportConfig  config)
inline

Assign a new transports configuration. By default peer-to-peer transports are enabled.

You may use this method to alter the configuration at any time, however sync will not begin until TryStartSync() is called.

Parameters
configThe new configuration to apply.

◆ 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. The network configuration can be customized using the SetTransportConfig method.

Exceptions
InvalidOperationExceptionThrown if the Ditto instance hasn't been activated by a successful call to SetLicenseToken.

◆ StopSync()

void DittoSDK.Ditto.StopSync ( )
inline

Stops all network transports.

You may continue to use the database 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.

◆ TryStartSync()

unsafe void DittoSDK.Ditto.TryStartSync ( )
inline

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

By default Ditto will enable all peer-to-peer transport types. The network configuration can be customized using the SetTransportConfig method.

Exceptions
DittoExceptionThrown if the Ditto instance hasn't been activated by a successful call to SetLicenseToken.

Property Documentation

◆ 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.SetLicenseToken(string) before interacting with the SDK.

◆ Auth

DittoAuthenticator DittoSDK.Ditto.Auth
get

Gets a DittoAuthenticator that provides access to authentication information and methods for logging on to Ditto Cloud.

◆ Authenticator

DittoAuthenticator DittoSDK.Ditto.Authenticator
get

Gets a DittoAuthenticator that provides access to authentication information and methods for logging on to Ditto Cloud.

◆ DeviceName

string DittoSDK.Ditto.DeviceName
getset

Gets or sets a custom identifier for the current device.

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. It does not need to be unique among peers. Configure the device name before calling TryStartSync(). If it is too long it may be truncated.

◆ IsSyncActive

bool DittoSDK.Ditto.IsSyncActive = false
get

A flag indicating whether or not sync is active. Use TryStartSync() to activate and StopSync() to deactivate sync.

◆ SDKVersion

unsafe string DittoSDK.Ditto.SDKVersion
get

Gets a string identifying the version of the Ditto SDK.

Returns
A string identifying the version of the Ditto SDK.

◆ SiteId

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

◆ Store

DittoStore DittoSDK.Ditto.Store
get

Gets a reference to the embedded data store.