A replicator is a background task that synchronizes changes between a local database and another database on a remote server (or on a peer device, or even another local database.) More...

Data Structures
struct	CBLProxySettings
	Proxy settings for the replicator. More...

struct	CBLReplicatorConfiguration
	The configuration of a replicator. More...

struct	CBLReplicatorProgress
	A fractional progress value, ranging from 0.0 to 1.0 as replication progresses. More...

struct	CBLReplicatorStatus
	A replicator's current status. More...

struct	CBLReplicatedDocument
	Information about a document that's been pushed or pulled. More...

Typedefs
typedef struct CBLReplicator	CBLReplicator
	A background task that syncs a CBLDatabase with a remote server or peer. More...

Configuration
enum	CBLReplicatorType : uint8_t { kCBLReplicatorTypePushAndPull = 0 , kCBLReplicatorTypePush , kCBLReplicatorTypePull }
	Direction of replication: push, pull, or both. More...

enum	CBLDocumentFlags : unsigned { kCBLDocumentFlagsDeleted = 1 << 0 , kCBLDocumentFlagsAccessRemoved = 1 << 1 }
	Flags describing a replicated document. More...

enum	CBLProxyType : uint8_t { kCBLProxyHTTP , kCBLProxyHTTPS }
	Types of proxy servers, for CBLProxySettings. More...

typedef struct CBLEndpoint	CBLEndpoint
	An opaque object representing the location of a database to replicate with. More...

typedef struct CBLAuthenticator	CBLAuthenticator
	An opaque object representing authentication credentials for a remote server. More...

typedef bool(*	CBLReplicationFilter) (void _cbl_nullable context, CBLDocument document, CBLDocumentFlags flags)
	A callback that can decide whether a particular document should be pushed or pulled. More...

typedef const CBLDocument _cbl_nullable(	CBLConflictResolver) (void _cbl_nullable context, FLString documentID, const CBLDocument _cbl_nullable localDocument, const CBLDocument *_cbl_nullable remoteDocument)
	Conflict-resolution callback for use in replications. More...

typedef FLSliceResult(*	CBLPropertyEncryptor) (void context, FLString documentID, FLDict properties, FLString keyPath, FLSlice input, FLStringResult algorithm, FLStringResult kid, CBLError error)
	Callback that encrypts CBLEncryptable properties in the documents pushed by the replicator. More...

typedef FLSliceResult(*	CBLPropertyDecryptor) (void context, FLString documentID, FLDict properties, FLString keyPath, FLSlice input, FLString algorithm, FLString kid, CBLError error)
	Callback that decrypts encrypted CBLEncryptable properties in documents pulled by the replicator. More...

CBL_PUBLIC const FLString	kCBLAuthDefaultCookieName
	The name of the HTTP cookie used by Sync Gateway to store session keys. More...

CBL_PUBLIC const CBLConflictResolver	CBLDefaultConflictResolver
	Default conflict resolver. More...

_cbl_warn_unused CBLEndpoint *_cbl_nullable	CBLEndpoint_CreateWithURL (FLString url, CBLError *_cbl_nullable outError)
	Creates a new endpoint representing a server-based database at the given URL. More...

_cbl_warn_unused CBLEndpoint *	CBLEndpoint_CreateWithLocalDB (CBLDatabase *)
	Creates a new endpoint representing another local database. More...

void	CBLEndpoint_Free (CBLEndpoint *_cbl_nullable)
	Frees a CBLEndpoint object. More...

_cbl_warn_unused CBLAuthenticator *	CBLAuth_CreatePassword (FLString username, FLString password)
	Creates an authenticator for HTTP Basic (username/password) auth. More...

_cbl_warn_unused CBLAuthenticator *	CBLAuth_CreateSession (FLString sessionID, FLString cookieName)
	Creates an authenticator using a Couchbase Sync Gateway login session identifier, and optionally a cookie name (pass NULL for the default.) More...

void	CBLAuth_Free (CBLAuthenticator *_cbl_nullable)
	Frees a CBLAuthenticator object. More...

Status and Progress
enum	CBLReplicatorActivityLevel : uint8_t { kCBLReplicatorStopped , kCBLReplicatorOffline , kCBLReplicatorConnecting , kCBLReplicatorIdle , kCBLReplicatorBusy }
	The possible states a replicator can be in during its lifecycle. More...

typedef void(*	CBLReplicatorChangeListener) (void _cbl_nullable context, CBLReplicator replicator, const CBLReplicatorStatus *status)
	A callback that notifies you when the replicator's status changes. More...

typedef void(*	CBLDocumentReplicationListener) (void context, CBLReplicator replicator, bool isPush, unsigned numDocuments, const CBLReplicatedDocument *documents)
	A callback that notifies you when documents are replicated. More...

CBLReplicatorStatus	CBLReplicator_Status (CBLReplicator *)
	Returns the replicator's current status. More...

_cbl_warn_unused FLDict _cbl_nullable	CBLReplicator_PendingDocumentIDs (CBLReplicator , CBLError _cbl_nullable outError)
	Indicates which documents have local changes that have not yet been pushed to the server by this replicator. More...

bool	CBLReplicator_IsDocumentPending (CBLReplicator repl, FLString docID, CBLError _cbl_nullable outError)
	Indicates whether the document with the given ID has local changes that have not yet been pushed to the server by this replicator. More...

_cbl_warn_unused CBLListenerToken *	CBLReplicator_AddChangeListener (CBLReplicator , CBLReplicatorChangeListener, void _cbl_nullable context)
	Adds a listener that will be called when the replicator's status changes. More...

_cbl_warn_unused CBLListenerToken *	CBLReplicator_AddDocumentReplicationListener (CBLReplicator , CBLDocumentReplicationListener, void _cbl_nullable context)
	Adds a listener that will be called when documents are replicated. More...

Lifecycle
static const CBLReplicator *	CBLReplicator_Retain (const CBLReplicator *t)

static void	CBLReplicator_Release (const CBLReplicator *t)

_cbl_warn_unused CBLReplicator *_cbl_nullable	CBLReplicator_Create (const CBLReplicatorConfiguration , CBLError _cbl_nullable outError)
	Creates a replicator with the given configuration. More...

const CBLReplicatorConfiguration *	CBLReplicator_Config (CBLReplicator *)
	Returns the configuration of an existing replicator. More...

void	CBLReplicator_Start (CBLReplicator *replicator, bool resetCheckpoint)
	Starts a replicator, asynchronously. More...

void	CBLReplicator_Stop (CBLReplicator *)
	Stops a running replicator, asynchronously. More...

void	CBLReplicator_SetHostReachable (CBLReplicator *, bool reachable)
	Informs the replicator whether it's considered possible to reach the remote host with the current network configuration. More...

void	CBLReplicator_SetSuspended (CBLReplicator *repl, bool suspended)
	Puts the replicator in or out of "suspended" state. More...

Detailed Description

A replicator is a background task that synchronizes changes between a local database and another database on a remote server (or on a peer device, or even another local database.)

Typedef Documentation

◆ CBLAuthenticator

typedef struct CBLAuthenticator CBLAuthenticator

An opaque object representing authentication credentials for a remote server.

◆ CBLConflictResolver

typedef const CBLDocument *_cbl_nullable(* CBLConflictResolver) (void *_cbl_nullable context, FLString documentID, const CBLDocument *_cbl_nullable localDocument, const CBLDocument *_cbl_nullable remoteDocument)

Conflict-resolution callback for use in replications.

This callback will be invoked when the replicator finds a newer server-side revision of a document that also has local changes. The local and remote changes must be resolved before the document can be pushed to the server.

Note: Any new CBLBlob objects set to the resolved document returned by the callback must not be released. They need to be retained for installation while the resolved document is being saved into the database, and the replicator will be responsible for releasing them after they are installed.

Warning: This callback will be called on a background thread managed by the replicator. It must pay attention to thread-safety. However, unlike a filter callback, it does not need to return quickly. If it needs to prompt for user input, that's OK.

Parameters

context	The `context` field of the CBLReplicatorConfiguration.
documentID	The ID of the conflicted document.
localDocument	The current revision of the document in the local database, or NULL if the local document has been deleted.
remoteDocument	The revision of the document found on the server, or NULL if the document has been deleted on the server.

Returns: The resolved document to save locally (and push, if the replicator is pushing.) This can be the same as localDocument or remoteDocument, or you can create a mutable copy of either one and modify it appropriately. Or return NULL if the resolution is to delete the document.

◆ CBLDocumentReplicationListener

typedef void(* CBLDocumentReplicationListener) (void *context, CBLReplicator *replicator, bool isPush, unsigned numDocuments, const CBLReplicatedDocument *documents)

A callback that notifies you when documents are replicated.

Warning: This callback will be called on a background thread managed by the replicator. It must pay attention to thread-safety. It should not take a long time to return, or it will slow down the replicator.

Parameters

context	The value given when the listener was added.
replicator	The replicator.
isPush	True if the document(s) were pushed, false if pulled.
numDocuments	The number of documents reported by this callback.
documents	An array with information about each document.

◆ CBLEndpoint

typedef struct CBLEndpoint CBLEndpoint

An opaque object representing the location of a database to replicate with.

◆ CBLPropertyDecryptor

typedef FLSliceResult(* CBLPropertyDecryptor) (void *context, FLString documentID, FLDict properties, FLString keyPath, FLSlice input, FLString algorithm, FLString kid, CBLError *error)

Callback that decrypts encrypted CBLEncryptable properties in documents pulled by the replicator.

The callback returns decrypted data as a FLSliceResult object, and the replicator will responsible for releasing the returned FLSliceResult object.

If an error occurred during decryption, return a null FLSliceResult with an error set to the out error parameter of the callback. There are two errors that are supported by the callback :

kCBLDomain / kCBLErrorCrypto : Permanent Crypto Error. When this error is set, the document will fail to replicate, and the document will not be synced again unless the document is updated, or the replicator is reset.
kCBLWebSocketDomain / 503 : Service Unavailable Error. This error is for mostly for a case such as when a crypto service is temporarily unavailable during decryption. When this error is set, the replicator will go into the offline state and will retry again according to the replicator retry logic. As a result, the document will be retried to replicate again, and the decryption callback will be called again to decrypt the properties of the document.

If the decryption should be skipped to retain the encrypted data as-is, return a null FLSliceResult object without setting an error set to the out error parameter.

Note: If an error besides the two errors above is set to the out error parameter of the callback, the document will be failed to replicate as getting the kCBLDomain / kCBLErrorCrypto error.; A null FLSliceResult can be created by calling FLSliceResult_CreateWith(nullptr, 0).

Parameters

context	Replicator’s context
documentID	Document ID
properties	Document properties
keyPath	Key path of the property to be decrypted
input	Property data to be decrypted
algorithm	Algorithm name
kid	Encryption key identifier specified when encryting the value
error	On return: error (Optional)

◆ CBLPropertyEncryptor

typedef FLSliceResult(* CBLPropertyEncryptor) (void *context, FLString documentID, FLDict properties, FLString keyPath, FLSlice input, FLStringResult *algorithm, FLStringResult *kid, CBLError *error)

Callback that encrypts CBLEncryptable properties in the documents pushed by the replicator.

The callback returns encrypted data as a FLSliceResult object, and the replicator will responsible for releasing the returned FLSliceResult object.

If an error occurred during encryption, return a null FLSliceResult with an error set to the out error parameter of the callback. There are two errors that are supported by the callback :

kCBLDomain / kCBLErrorCrypto : Permanent Crypto Error. When this error is set, the document will fail to replicate, and the document will not be synced again unless the document is updated, or the replicator is reset.
kCBLWebSocketDomain / 503 : Service Unavailable Error. This error is for mostly for a case such as when a crypto service is temporarily unavailable during encryption. When this error is set, the replicator will go into the offline state and will retry again according to the replicator retry logic. As a result, the document will be retried to replicate again, and the encryption callback will be called again to encrypt the properties of the document.

Note: If an error besides the two errors above is set to the out error parameter of the callback, or only a null FLSliceResult object is returned without setting an error, the document will be failed to replicate as the kCBLDomain / kCBLErrorCrypto error is sepecified.; A null FLSliceResult can be created by calling FLSliceResult_CreateWith(nullptr, 0).

Parameters

context	Replicator’s context
documentID	Document ID
properties	Document properties
keyPath	Key path of the property to be encrypted
input	Property data to be encrypted
algorithm	On return: algorithm name (Optional: Default Value is 'CB_MOBILE_CUSTOM')
kid	On return: encryption key identifier (Optional)
error	On return: error (Optional)

◆ CBLReplicationFilter

typedef bool(* CBLReplicationFilter) (void *_cbl_nullable context, CBLDocument *document, CBLDocumentFlags flags)

A callback that can decide whether a particular document should be pushed or pulled.

Warning: This callback will be called on a background thread managed by the replicator. It must pay attention to thread-safety. It should not take a long time to return, or it will slow down the replicator.

Parameters

context	The `context` field of the CBLReplicatorConfiguration.
document	The document in question.
flags	Indicates whether the document was deleted or removed.

Returns: True if the document should be replicated, false to skip it.

◆ CBLReplicator

typedef struct CBLReplicator CBLReplicator

A background task that syncs a CBLDatabase with a remote server or peer.

◆ CBLReplicatorChangeListener

typedef void(* CBLReplicatorChangeListener) (void *_cbl_nullable context, CBLReplicator *replicator, const CBLReplicatorStatus *status)

A callback that notifies you when the replicator's status changes.

Warning: This callback will be called on a background thread managed by the replicator. It must pay attention to thread-safety. It should not take a long time to return, or it will slow down the replicator.

Parameters

context	The value given when the listener was added.
replicator	The replicator.
status	The replicator's status.

Enumeration Type Documentation

◆ CBLDocumentFlags

enum CBLDocumentFlags : unsigned

Flags describing a replicated document.

Enumerator
kCBLDocumentFlagsDeleted	The document has been deleted.
kCBLDocumentFlagsAccessRemoved	Lost access to the document on the server.

◆ CBLProxyType

enum CBLProxyType : uint8_t

Types of proxy servers, for CBLProxySettings.

Enumerator
kCBLProxyHTTP	HTTP proxy; must support 'CONNECT' method.
kCBLProxyHTTPS	HTTPS proxy; must support 'CONNECT' method.

◆ CBLReplicatorActivityLevel

enum CBLReplicatorActivityLevel : uint8_t

The possible states a replicator can be in during its lifecycle.

Enumerator
kCBLReplicatorStopped	The replicator is unstarted, finished, or hit a fatal error.
kCBLReplicatorOffline	The replicator is offline, as the remote host is unreachable.
kCBLReplicatorConnecting	The replicator is connecting to the remote host.
kCBLReplicatorIdle	The replicator is inactive, waiting for changes to sync.
kCBLReplicatorBusy	The replicator is actively transferring data.

◆ CBLReplicatorType

enum CBLReplicatorType : uint8_t

Direction of replication: push, pull, or both.

Enumerator
kCBLReplicatorTypePushAndPull	Bidirectional; both push and pull.
kCBLReplicatorTypePush	Pushing changes to the target.
kCBLReplicatorTypePull	Pulling changes from the target.

Function Documentation

◆ CBLAuth_CreatePassword()

_cbl_warn_unused CBLAuthenticator * CBLAuth_CreatePassword	(	FLString	username,
		FLString	password
	)

Creates an authenticator for HTTP Basic (username/password) auth.

◆ CBLAuth_CreateSession()

_cbl_warn_unused CBLAuthenticator * CBLAuth_CreateSession	(	FLString	sessionID,
		FLString	cookieName
	)

Creates an authenticator using a Couchbase Sync Gateway login session identifier, and optionally a cookie name (pass NULL for the default.)

◆ CBLAuth_Free()

void CBLAuth_Free ( CBLAuthenticator * _cbl_nullable )

Frees a CBLAuthenticator object.

◆ CBLEndpoint_CreateWithLocalDB()

_cbl_warn_unused CBLEndpoint * CBLEndpoint_CreateWithLocalDB ( CBLDatabase * )

Creates a new endpoint representing another local database.

(Enterprise Edition only.)

◆ CBLEndpoint_CreateWithURL()

_cbl_warn_unused CBLEndpoint *_cbl_nullable CBLEndpoint_CreateWithURL	(	FLString	url,
		CBLError *_cbl_nullable	outError
	)

Creates a new endpoint representing a server-based database at the given URL.

The URL's scheme must be ws or wss, it must of course have a valid hostname, and its path must be the name of the database on that server.

The port can be omitted; it defaults to 80 for ws and 443 for wss. For example: wss://example.org/dbname.

If an invalid endpoint URL is specified, an error will be returned.

◆ CBLEndpoint_Free()

void CBLEndpoint_Free ( CBLEndpoint * _cbl_nullable )

Frees a CBLEndpoint object.

◆ CBLReplicator_AddChangeListener()

_cbl_warn_unused CBLListenerToken * CBLReplicator_AddChangeListener	(	CBLReplicator *	,
		CBLReplicatorChangeListener	,
		void *_cbl_nullable	context
	)

Adds a listener that will be called when the replicator's status changes.

◆ CBLReplicator_AddDocumentReplicationListener()

_cbl_warn_unused CBLListenerToken * CBLReplicator_AddDocumentReplicationListener	(	CBLReplicator *	,
		CBLDocumentReplicationListener	,
		void *_cbl_nullable	context
	)

Adds a listener that will be called when documents are replicated.

◆ CBLReplicator_Config()

const CBLReplicatorConfiguration * CBLReplicator_Config ( CBLReplicator * )

Returns the configuration of an existing replicator.

◆ CBLReplicator_Create()

_cbl_warn_unused CBLReplicator *_cbl_nullable CBLReplicator_Create	(	const CBLReplicatorConfiguration *	,
		CBLError *_cbl_nullable	outError
	)

Creates a replicator with the given configuration.

◆ CBLReplicator_IsDocumentPending()

bool CBLReplicator_IsDocumentPending	(	CBLReplicator *	repl,
		FLString	docID,
		CBLError *_cbl_nullable	outError
	)

Indicates whether the document with the given ID has local changes that have not yet been pushed to the server by this replicator.

This is equivalent to, but faster than, calling CBLReplicator_PendingDocumentIDs and checking whether the result contains docID. See that function's documentation for details.

Note: A false result means the document is not pending, or there was an error. To tell the difference, compare the error code to zero.

◆ CBLReplicator_PendingDocumentIDs()

_cbl_warn_unused FLDict _cbl_nullable CBLReplicator_PendingDocumentIDs	(	CBLReplicator *	,
		CBLError *_cbl_nullable	outError
	)

Indicates which documents have local changes that have not yet been pushed to the server by this replicator.

This is of course a snapshot, that will go out of date as the replicator makes progress and/or documents are saved locally.

The result is, effectively, a set of document IDs: a dictionary whose keys are the IDs and values are true. If there are no pending documents, the dictionary is empty. On error, NULL is returned.

Note: This function can be called on a stopped or un-started replicator.; Documents that would never be pushed by this replicator, due to its configuration's pushFilter or docIDs, are ignored.

Warning: You are responsible for releasing the returned array via FLValue_Release.

◆ CBLReplicator_Release()

static void CBLReplicator_Release ( const CBLReplicator * t )

inlinestatic

◆ CBLReplicator_Retain()

static const CBLReplicator * CBLReplicator_Retain ( const CBLReplicator * t )

inlinestatic

◆ CBLReplicator_SetHostReachable()

void CBLReplicator_SetHostReachable	(	CBLReplicator *	,
		bool	reachable
	)

Informs the replicator whether it's considered possible to reach the remote host with the current network configuration.

The default value is true. This only affects the replicator's behavior while it's in the Offline state: Setting it to false will cancel any pending retry and prevent future automatic retries. Setting it back to true will initiate an immediate retry.

◆ CBLReplicator_SetSuspended()

void CBLReplicator_SetSuspended	(	CBLReplicator *	repl,
		bool	suspended
	)

Puts the replicator in or out of "suspended" state.

The default is false. Setting suspended=true causes the replicator to disconnect and enter Offline state; it will not attempt to reconnect while it's suspended. Setting suspended=false causes the replicator to attempt to reconnect, if it was connected when suspended, and is still in Offline state.

◆ CBLReplicator_Start()

void CBLReplicator_Start	(	CBLReplicator *	replicator,
		bool	resetCheckpoint
	)

Starts a replicator, asynchronously.

Does nothing if it's already started.

Parameters

replicator	The replicator instance.
resetCheckpoint	If true, the persistent saved state ("checkpoint") for this replication will be discarded, causing it to re-scan all documents. This significantly increases time and bandwidth (redundant docs are not transferred, but their IDs are) but can resolve unexpected problems with missing documents if one side or the other has gotten out of sync.

◆ CBLReplicator_Status()

CBLReplicatorStatus CBLReplicator_Status ( CBLReplicator * )

Returns the replicator's current status.

◆ CBLReplicator_Stop()

void CBLReplicator_Stop ( CBLReplicator * )

Stops a running replicator, asynchronously.

Does nothing if it's not already started. The replicator will call your CBLReplicatorChangeListener with an activity level of kCBLReplicatorStopped after it stops. Until then, consider it still active.

Variable Documentation

◆ CBLDefaultConflictResolver

CBL_PUBLIC const CBLConflictResolver CBLDefaultConflictResolver

extern

Default conflict resolver.

This always returns localDocument.

◆ kCBLAuthDefaultCookieName

CBL_PUBLIC const FLString kCBLAuthDefaultCookieName

extern

The name of the HTTP cookie used by Sync Gateway to store session keys.

Data Structures

Typedefs

Configuration

Status and Progress

Lifecycle

Detailed Description

Typedef Documentation

◆ CBLAuthenticator

◆ CBLConflictResolver

◆ CBLDocumentReplicationListener

◆ CBLEndpoint

◆ CBLPropertyDecryptor

◆ CBLPropertyEncryptor

◆ CBLReplicationFilter

◆ CBLReplicator

◆ CBLReplicatorChangeListener

Enumeration Type Documentation

◆ CBLDocumentFlags

◆ CBLProxyType

◆ CBLReplicatorActivityLevel

◆ CBLReplicatorType

Function Documentation

◆ CBLAuth_CreatePassword()

◆ CBLAuth_CreateSession()

◆ CBLAuth_Free()

◆ CBLEndpoint_CreateWithLocalDB()

◆ CBLEndpoint_CreateWithURL()

◆ CBLEndpoint_Free()

◆ CBLReplicator_AddChangeListener()

◆ CBLReplicator_AddDocumentReplicationListener()

◆ CBLReplicator_Config()

◆ CBLReplicator_Create()

◆ CBLReplicator_IsDocumentPending()

◆ CBLReplicator_PendingDocumentIDs()

◆ CBLReplicator_Release()

◆ CBLReplicator_Retain()

◆ CBLReplicator_SetHostReachable()

◆ CBLReplicator_SetSuspended()

◆ CBLReplicator_Start()

◆ CBLReplicator_Status()

◆ CBLReplicator_Stop()

Variable Documentation

◆ CBLDefaultConflictResolver

◆ kCBLAuthDefaultCookieName