DITDitto
@interface DITDitto : NSObject
The entrypoint to the Ditto SDK.
For a DITDitto
instance to continue to connect to other devices it must be kept in scope.
-
Configure 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
startSync
. If it is too long it may be truncated.Declaration
Objective-C
@property (nonatomic) NSString *_Nonnull deviceName;
-
Provides access to the SDK’s store functionality.
Declaration
Objective-C
@property (readonly) DITStore *_Nonnull store;
-
Provides access to authentication information and methods for logging on to Ditto Cloud.
Declaration
Objective-C
@property (nonatomic, readonly, nullable) DITAuthenticator *auth;
-
Provides access to the instance’s identity information.
Declaration
Objective-C
@property (nonatomic, readonly) DITIdentity *_Nonnull identity;
-
A flag indicating whether or not the SDK has been activated with a valid license token.
Declaration
Objective-C
@property (nonatomic, readonly, getter=isActivated) BOOL activated;
-
Deprecated
use
isActivated
getter instead.A flag indicating whether or not the SDK has been activated with a valid license token.
Declaration
Objective-C
- (BOOL)activated;
-
A flag indicating whether or not sync is active. Use
tryStartSync
to activate sync andstopSync
to deactivate sync.Declaration
Objective-C
@property (nonatomic, readonly, getter=isSyncActive) BOOL syncActive;
-
The site ID that the instance of
DITDitto
is using as part of its identity.Declaration
Objective-C
@property (nonatomic, readonly) uint64_t siteID;
-
An optional delegate that will be called with SDK lifecycle information if defined.
Declaration
Objective-C
@property (nonatomic, weak) id<DITDittoDelegate> _Nullable delegate;
-
The dispatch queue that will be used to deliver delegate events. Defaults to the main queue.
Declaration
Objective-C
@property (nonatomic) dispatch_queue_t _Nonnull delegateEventQueue;
-
Indicates whether history tracking is enabled or not.
Warning
History Tracking is experimental and shouldn’t be used in production.Declaration
Objective-C
@property (nonatomic, readonly, getter=isHistoryTrackingEnabled) BOOL historyTrackingEnabled;
-
Initializes a new
DITDitto
. This will initialize an instance ofDITDitto
with the default configuration.Declaration
Objective-C
- (nonnull instancetype)init;
-
Initializes a new
DITDitto
.Declaration
Objective-C
- (nonnull instancetype)initWithIdentity:(nonnull DITIdentity *)identity;
Parameters
identity
Provide the identity of the entity that is interacting with Ditto.
-
Initializes a new
DITDitto
.Warning
History Tracking is experimental and shouldn’t be used in production.
Declaration
Objective-C
- (nonnull instancetype)initWithIdentity:(nonnull DITIdentity *)identity historyTrackingEnabled:(BOOL)historyTrackingEnabled;
Parameters
identity
Provide the identity of the entity that is interacting with Ditto.
historyTrackingEnabled
Whether or not you want history tracking enabled.
-
Initializes a new
DITDitto
.Declaration
Objective-C
- (nonnull instancetype)initWithIdentity:(nonnull DITIdentity *)identity persistenceDirectory:(nullable NSURL *)directory;
Parameters
identity
Provide the identity of the entity that is interacting with Ditto.
directory
The directory that will be used to persist Ditto data.
-
Initializes a new
DITDitto
.Warning
History Tracking is experimental and shouldn’t be used in production.
Declaration
Objective-C
- (nonnull instancetype)initWithIdentity:(nonnull DITIdentity *)identity historyTrackingEnabled:(BOOL)historyTrackingEnabled persistenceDirectory:(nullable NSURL *)directory;
Parameters
identity
Provide the identity of the entity that is interacting with Ditto.
historyTrackingEnabled
Whether or not you want history tracking enabled.
directory
The directory that will be used to persist Ditto data.
-
Deprecated
use
tryStartSync
instead.Starts the network transports. Ditto will connect to other devices and sync with them where appropriate.
By default Ditto will enable all peer-to-peer transport types. On iOS this means Bluetooth, WiFi and AWDL. The network configuration can be customized using the
setTransportConfig
method.Declaration
Objective-C
- (void)startSync;
-
Starts the network transports. Ditto will connect to other devices and sync with them where appropriate.
By default Ditto will enable all peer-to-peer transport types. On iOS this means Bluetooth, WiFi and AWDL. The network configuration can be customized using the
setTransportConfig
method.You must have activated Ditto with a successful call to
setLicenseToken
before starting sync.Declaration
Objective-C
- (BOOL)tryStartSync:(NSError *_Nullable *_Nullable)error;
Parameters
error
On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.
Return Value
YES
if sync was successfully started.NO
otherwise. -
Stops all network transports.
You may continue to use the database locally but no data will sync to or from other devices.
Declaration
Objective-C
- (void)stopSync;
-
Assign a new transports configuration. By default peer-to-peer transports (Bluetooth, WiFi and AWDL) are enabled.
You may use this method to alter the configuration at any time. Sync will not begin until
startSync
is called.Declaration
Objective-C
- (void)setTransportConfig:(nonnull DITTransportConfig *)config;
-
Deprecated
use
setLicenseToken
instead.Activate a
DITDitto
instance by setting an access license. You cannot sync data across instances using an offline (Development, OfflinePlayground, Manual or SharedKey)DITDitto
instance before you have activated it.Declaration
Objective-C
- (void)setAccessLicense:(nonnull NSString *)license;
Parameters
license
The license to activate the
DITDitto
instance with, which you can find on the Ditto portal (https://portal.ditto.live). -
Deprecated
use
setOfflineOnlyLicenseToken
instead.Activate an offline
DITDitto
instance by setting a license token. You cannot sync data across instances using an offline (Development, OfflinePlayground, Manual or SharedKey)DITDitto
instance before you have activated it.Declaration
Objective-C
- (BOOL)setLicenseToken:(nonnull NSString *)licenseToken error:(NSError *_Nullable *_Nullable)error;
Parameters
licenseToken
The license token to activate the
DITDitto
instance with, which you can find on the Ditto portal (https://portal.ditto.live).error
On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.
Return Value
YES
if the license token was successfully set and theDITDitto
instance is now activated for sync.NO
otherwise. -
Activate an offline
DITDitto
instance by setting a license token. You cannot sync data across instances using an offline (Development, OfflinePlayground, Manual or SharedKey)DITDitto
instance before you have activated it.Declaration
Objective-C
- (BOOL)setOfflineOnlyLicenseToken:(nonnull NSString *)licenseToken error:(NSError *_Nullable *_Nullable)error;
Parameters
licenseToken
The license token to activate the
DITDitto
instance with, which you can find on the Ditto portal (https://portal.ditto.live).error
On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.
Return Value
YES
if the license token was successfully set and theDITDitto
instance is now activated for sync.NO
otherwise. -
Request bulk status information about the transports.
This is mostly intended for statistical or debugging purposes.
Declaration
Objective-C
- (nullable DITTransportDiagnostics *)transportDiagnostics: (NSError *_Nullable *_Nullable)error;
Parameters
error
On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.
Return Value
An instance of
DITTransportDiagnostics
ornil
if there was an error. -
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.
Declaration
Objective-C
- (nonnull id<DITObserver>)observePeers: (nonnull void (^)(NSArray<DITRemotePeer *> *_Nonnull))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.
Declaration
Objective-C
- (nonnull id<DITObserver>)observePeersV2: (nonnull void (^)(NSString *_Nonnull))callback;
-
Returns a string identifying the version of the Ditto SDK.
Declaration
Objective-C
- (nonnull NSString *)sdkVersion;
-
The default location of Ditto data files when no persistence directory is specified.
Declaration
Objective-C
+ (nonnull NSURL *)defaultDittoDirectory:(nonnull NSFileManager *)fileManager;
-
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.
Declaration
Objective-C
- (void)runGarbageCollection;