Replicator

Data Structures
struct	C4Address
	A simple parsed-URL type. More...
struct	C4Progress
	Represents the current progress of a replicator. More...
struct	C4ReplicatorStatus
	Current status of replication. More...
struct	C4DocumentEnded
	Information about a document that's been pushed or pulled. More...
struct	C4ReplicationCollection
struct	C4ReplicatorParameters
	Parameters describing a replication, used when creating a C4Replicator. More...

Macros
#define	kC4Replicator2Scheme   C4STR("ws")
#define	kC4Replicator2TLSScheme   C4STR("wss")
#define	kC4ReplicatorOptionDocIDs   "docIDs"
	Docs to replicate (string[])
#define	kC4ReplicatorOptionChannels   "channels"
	SG channel names (string[])
#define	kC4ReplicatorOptionFilter   "filter"
	Pull filter name (string)
#define	kC4ReplicatorOptionFilterParams   "filterParams"
	Pull filter params (Dict[string])
#define	kC4ReplicatorOptionSkipDeleted   "skipDeleted"
	Don't push/pull tombstones (bool)
#define	kC4ReplicatorOptionNoIncomingConflicts   "noIncomingConflicts"
	Reject incoming conflicts (bool)
#define	kC4ReplicatorCheckpointInterval   "checkpointInterval"
	How often to checkpoint, in seconds (number)
#define	kC4ReplicatorOptionRemoteDBUniqueID   "remoteDBUniqueID"
	Stable ID for remote db with unstable URL (string)
#define	kC4ReplicatorOptionDisableDeltas   "noDeltas"
	Disables delta sync (bool)
#define	kC4ReplicatorOptionDisablePropertyDecryption   "noDecryption"
	Disables property decryption (bool)
#define	kC4ReplicatorOptionMaxRetries   "maxRetries"
	Max number of retry attempts (int)
#define	kC4ReplicatorOptionMaxRetryInterval   "maxRetryInterval"
	Max delay betw retries (secs)
#define	kC4ReplicatorOptionAutoPurge   "autoPurge"
	Enables auto purge; default is true (bool)
#define	kC4ReplicatorOptionAcceptParentDomainCookies   "acceptParentDomainCookies"
#define	kC4ReplicatorOptionRootCerts   "rootCerts"
	Trusted root certs (data)
#define	kC4ReplicatorOptionPinnedServerCert   "pinnedCert"
	Cert or public key (data)
#define	kC4ReplicatorOptionOnlySelfSignedServerCert    "onlySelfSignedServer"
	Only accept self signed server certs (for P2P, bool)
#define	kC4ReplicatorOptionExtraHeaders   "headers"
	Extra HTTP headers (string[])
#define	kC4ReplicatorOptionCookies   "cookies"
	HTTP Cookie header value (string)
#define	kC4ReplicatorOptionAuthentication   "auth"
	Auth settings (Dict); see [1].
#define	kC4ReplicatorOptionProxyServer   "proxy"
	Proxy settings (Dict); see [3]].
#define	kC4ReplicatorHeartbeatInterval   "heartbeat"
	Interval in secs to send a keepalive ping.
#define	kC4SocketOptionWSProtocols   "WS-Protocols"
	Sec-WebSocket-Protocol header value.
#define	kC4SocketOptionNetworkInterface    "networkInterface"
	Specific network interface (name or IP address) used for connecting to the remote server.
#define	kC4ReplicatorCompressionLevel   "BLIPCompressionLevel"
	Data compression level, 0..9.
#define	kC4ReplicatorAuthType   "type"
	Auth type; see [2] (string)
#define	kC4ReplicatorAuthUserName   "username"
	User name for basic auth (string)
#define	kC4ReplicatorAuthPassword   "password"
	Password for basic auth (string)
#define	kC4ReplicatorAuthEnableChallengeAuth    "challengeAuth"
	Use challenge auth instead of preemptive auth for basic auth, default is false (bool); \ Implemented by BuiltInWebSocket.
#define	kC4ReplicatorAuthClientCert   "clientCert"
	TLS client certificate (value platform-dependent)
#define	kC4ReplicatorAuthClientCertKey   "clientCertKey"
	Client cert's private key (data)
#define	kC4ReplicatorAuthToken   "token"
	Session cookie or auth token (string)
#define	kC4AuthTypeBasic   "Basic"
	HTTP Basic (the default)
#define	kC4AuthTypeSession   "Session"
	SG session cookie.
#define	kC4AuthTypeOpenIDConnect   "OpenID Connect"
	OpenID Connect token.
#define	kC4AuthTypeFacebook   "Facebook"
	Facebook auth token.
#define	kC4AuthTypeClientCert   "Client Cert"
	TLS client cert.
#define	kC4ReplicatorProxyType   "type"
	Proxy type; see [4] (string)
#define	kC4ReplicatorProxyHost   "host"
	Proxy hostname (string)
#define	kC4ReplicatorProxyPort   "port"
	Proxy port number (integer)
#define	kC4ReplicatorProxyAuth   "auth"
	Proxy auth (Dict); see above.
#define	kC4ProxyTypeNone   "none"
	Use no proxy (overrides system setting)
#define	kC4ProxyTypeHTTP   "HTTP"
	HTTP proxy (using CONNECT method)
#define	kC4ProxyTypeHTTPS   "HTTPS"
	HTTPS proxy (using CONNECT method)
#define	kC4ProxyTypeSOCKS   "SOCKS"
	SOCKS proxy.

Typedefs
typedef void(*	C4ReplicatorStatusChangedCallback) (C4Replicator *, C4ReplicatorStatus, void *context)
	Callback a client can register, to get progress information.
typedef void(*	C4ReplicatorDocumentsEndedCallback) (C4Replicator *, bool pushing, size_t numDocs, const C4DocumentEnded *docs[], void *context)
	Callback a client can register, to hear about the replication status of documents.
typedef void(*	C4ReplicatorBlobProgressCallback) (C4Replicator *, bool pushing, C4CollectionSpec collectionSpec, C4String docID, C4String docProperty, C4BlobKey blobKey, uint64_t bytesComplete, uint64_t bytesTotal, C4Error error, void *context)
	Callback a client can register, to hear about the status of blobs.
typedef bool(*	C4ReplicatorValidationFunction) (C4CollectionSpec collectionSpec, C4String docID, C4String revID, C4RevisionFlags, FLDict body, void *context)
	Callback that can choose to reject an incoming pulled revision, or stop a local revision from being pushed, by returning false.
typedef void *	C4ReplicatorPropertyEncryptionCallback
typedef void *	C4ReplicatorPropertyDecryptionCallback

Enumerations
enum	C4ReplicatorMode : int32_t { kC4Disabled , kC4Passive , kC4OneShot , kC4Continuous }
enum	C4ReplicatorActivityLevel : int32_t {   kC4Stopped , kC4Offline , kC4Connecting , kC4Idle ,   kC4Busy , kC4Stopping }
enum	C4ReplicatorStatusFlags : int32_t { kC4WillRetry = 0x1 , kC4HostReachable = 0x2 , kC4Suspended = 0x4 }
enum	C4ReplicatorProgressLevel : int32_t { kC4ReplProgressOverall , kC4ReplProgressPerDocument , kC4ReplProgressPerAttachment }

Functions
CBL_CORE_API bool	c4repl_isValidDatabaseName (C4String dbName)
	Checks whether a database name is valid, for purposes of appearing in a replication URL.
NODISCARD CBL_CORE_API bool	c4repl_isValidRemote (C4Address remoteAddress, C4String remoteDatabaseName, C4Error *outError)
	Checks whether the destination of a replication is valid.
NODISCARD CBL_CORE_API bool	c4address_fromURL (C4String url, C4Address *address, C4String *dbName)
	A simple URL parser that populates a C4Address from a URL string.
CBL_CORE_API C4StringResult	c4address_toURL (C4Address address)
	Converts a C4Address to a URL.
NODISCARD CBL_CORE_API C4Replicator *	c4repl_new (C4Database *db, C4Address remoteAddress, C4String remoteDatabaseName, C4ReplicatorParameters params, C4String logPrefix, C4Error *outError)
	Creates a new networked replicator.
NODISCARD CBL_CORE_API C4Replicator *	c4repl_newWithSocket (C4Database *db, C4Socket *openSocket, C4ReplicatorParameters params, C4String logPrefix, C4Error *outError)
	Creates a new replicator from an already-open C4Socket.
CBL_CORE_API void	c4repl_start (C4Replicator *repl, bool reset)
	Tells a replicator to start.
CBL_CORE_API void	c4repl_stop (C4Replicator *repl)
	Tells a replicator to stop.
NODISCARD CBL_CORE_API bool	c4repl_retry (C4Replicator *repl, C4Error *outError)
	Tells a replicator that's in the offline state to reconnect immediately.
CBL_CORE_API void	c4repl_setHostReachable (C4Replicator *repl, bool reachable)
	Informs the replicator whether it's considered possible to reach the remote host with the current network configuration.
CBL_CORE_API void	c4repl_setSuspended (C4Replicator *repl, bool suspended)
	Puts the replicator in or out of "suspended" state.
CBL_CORE_API void	c4repl_setOptions (C4Replicator *repl, C4Slice optionsDictFleece)
	Sets the replicator's options dictionary.
CBL_CORE_API C4ReplicatorStatus	c4repl_getStatus (C4Replicator *repl)
	Returns the current state of a replicator.
CBL_CORE_API C4Slice	c4repl_getResponseHeaders (C4Replicator *repl)
	Returns the HTTP response headers as a Fleece-encoded dictionary.
CBL_CORE_API C4SliceResult	c4repl_getPendingDocIDs (C4Replicator *repl, C4CollectionSpec spec, C4Error *outErr)
	Gets a fleece encoded list of IDs of documents who have revisions pending push.
NODISCARD CBL_CORE_API bool	c4repl_isDocumentPending (C4Replicator *repl, C4String docID, C4CollectionSpec spec, C4Error *outErr)
	Checks if the document with the given ID has revisions pending push.
NODISCARD CBL_CORE_API C4Cert *	c4repl_getPeerTLSCertificate (C4Replicator *repl, C4Error *outErr)
	Gets the TLS certificate, if any, that was sent from the remote server (NOTE: Only functions when using BuiltInWebSocket)
NODISCARD CBL_CORE_API bool	c4repl_setProgressLevel (C4Replicator *repl, C4ReplicatorProgressLevel level, C4Error *outErr)
	Sets the progress level of the replicator, indicating what information should be provided via callback.
NODISCARD CBL_CORE_API bool	c4db_setCookie (C4Database *db, C4String setCookieHeader, C4String fromHost, C4String fromPath, bool acceptParentDomain, C4Error *outError)
	Takes the value of a "Set-Cookie:" header, received from the given host, from an HTTP request with the given path, and saves the cookie into the database's cookie store.
CBL_CORE_API C4StringResult	c4db_getCookies (C4Database *db, C4Address request, C4Error *error)
	Locates any saved HTTP cookies relevant to the given request, and returns them as a string that can be used as the value of a "Cookie:" header.
CBL_CORE_API void	c4db_clearCookies (C4Database *db)
	Removes all cookies from the database's cookie store.

Variables
CBL_CORE_API const char *const	kC4ReplicatorActivityLevelNames [6]
	For convenience, an array of C strings naming the C4ReplicatorActivityLevel values.

Detailed Description

Macro Definition Documentation

kC4AuthTypeBasic

#define kC4AuthTypeBasic   "Basic"

HTTP Basic (the default)

kC4AuthTypeClientCert

#define kC4AuthTypeClientCert   "Client Cert"

TLS client cert.

kC4AuthTypeFacebook

#define kC4AuthTypeFacebook   "Facebook"

Facebook auth token.

kC4AuthTypeOpenIDConnect

#define kC4AuthTypeOpenIDConnect   "OpenID Connect"

OpenID Connect token.

kC4AuthTypeSession

#define kC4AuthTypeSession   "Session"

SG session cookie.

kC4ProxyTypeHTTP

#define kC4ProxyTypeHTTP   "HTTP"

HTTP proxy (using CONNECT method)

kC4ProxyTypeHTTPS

#define kC4ProxyTypeHTTPS   "HTTPS"

HTTPS proxy (using CONNECT method)

kC4ProxyTypeNone

#define kC4ProxyTypeNone   "none"

Use no proxy (overrides system setting)

kC4ProxyTypeSOCKS

#define kC4ProxyTypeSOCKS   "SOCKS"

SOCKS proxy.

kC4Replicator2Scheme

#define kC4Replicator2Scheme   C4STR("ws")

kC4Replicator2TLSScheme

#define kC4Replicator2TLSScheme   C4STR("wss")

kC4ReplicatorAuthClientCert

#define kC4ReplicatorAuthClientCert   "clientCert"

TLS client certificate (value platform-dependent)

kC4ReplicatorAuthClientCertKey

#define kC4ReplicatorAuthClientCertKey   "clientCertKey"

Client cert's private key (data)

kC4ReplicatorAuthEnableChallengeAuth

#define kC4ReplicatorAuthEnableChallengeAuth    "challengeAuth"

Use challenge auth instead of preemptive auth for basic auth, default is false (bool); \ Implemented by BuiltInWebSocket.

kC4ReplicatorAuthPassword

#define kC4ReplicatorAuthPassword   "password"

Password for basic auth (string)

kC4ReplicatorAuthToken

#define kC4ReplicatorAuthToken   "token"

Session cookie or auth token (string)

kC4ReplicatorAuthType

#define kC4ReplicatorAuthType   "type"

Auth type; see [2] (string)

kC4ReplicatorAuthUserName

#define kC4ReplicatorAuthUserName   "username"

User name for basic auth (string)

kC4ReplicatorCheckpointInterval

#define kC4ReplicatorCheckpointInterval   "checkpointInterval"

How often to checkpoint, in seconds (number)

kC4ReplicatorCompressionLevel

#define kC4ReplicatorCompressionLevel   "BLIPCompressionLevel"

Data compression level, 0..9.

kC4ReplicatorHeartbeatInterval

#define kC4ReplicatorHeartbeatInterval   "heartbeat"

Interval in secs to send a keepalive ping.

kC4ReplicatorOptionAcceptParentDomainCookies

#define kC4ReplicatorOptionAcceptParentDomainCookies   "acceptParentDomainCookies"

kC4ReplicatorOptionAuthentication

#define kC4ReplicatorOptionAuthentication   "auth"

Auth settings (Dict); see [1].

kC4ReplicatorOptionAutoPurge

#define kC4ReplicatorOptionAutoPurge   "autoPurge"

Enables auto purge; default is true (bool)

kC4ReplicatorOptionChannels

#define kC4ReplicatorOptionChannels   "channels"

SG channel names (string[])

kC4ReplicatorOptionCookies

#define kC4ReplicatorOptionCookies   "cookies"

HTTP Cookie header value (string)

kC4ReplicatorOptionDisableDeltas

#define kC4ReplicatorOptionDisableDeltas   "noDeltas"

Disables delta sync (bool)

kC4ReplicatorOptionDisablePropertyDecryption

#define kC4ReplicatorOptionDisablePropertyDecryption   "noDecryption"

Disables property decryption (bool)

kC4ReplicatorOptionDocIDs

#define kC4ReplicatorOptionDocIDs   "docIDs"

Docs to replicate (string[])

kC4ReplicatorOptionExtraHeaders

#define kC4ReplicatorOptionExtraHeaders   "headers"

Extra HTTP headers (string[])

kC4ReplicatorOptionFilter

#define kC4ReplicatorOptionFilter   "filter"

Pull filter name (string)

kC4ReplicatorOptionFilterParams

#define kC4ReplicatorOptionFilterParams   "filterParams"

Pull filter params (Dict[string])

kC4ReplicatorOptionMaxRetries

#define kC4ReplicatorOptionMaxRetries   "maxRetries"

Max number of retry attempts (int)

kC4ReplicatorOptionMaxRetryInterval

#define kC4ReplicatorOptionMaxRetryInterval   "maxRetryInterval"

Max delay betw retries (secs)

kC4ReplicatorOptionNoIncomingConflicts

#define kC4ReplicatorOptionNoIncomingConflicts   "noIncomingConflicts"

Reject incoming conflicts (bool)

kC4ReplicatorOptionOnlySelfSignedServerCert

#define kC4ReplicatorOptionOnlySelfSignedServerCert    "onlySelfSignedServer"

Only accept self signed server certs (for P2P, bool)

kC4ReplicatorOptionPinnedServerCert

#define kC4ReplicatorOptionPinnedServerCert   "pinnedCert"

Cert or public key (data)

kC4ReplicatorOptionProxyServer

#define kC4ReplicatorOptionProxyServer   "proxy"

Proxy settings (Dict); see [3]].

kC4ReplicatorOptionRemoteDBUniqueID

#define kC4ReplicatorOptionRemoteDBUniqueID   "remoteDBUniqueID"

Stable ID for remote db with unstable URL (string)

kC4ReplicatorOptionRootCerts

#define kC4ReplicatorOptionRootCerts   "rootCerts"

Trusted root certs (data)

kC4ReplicatorOptionSkipDeleted

#define kC4ReplicatorOptionSkipDeleted   "skipDeleted"

Don't push/pull tombstones (bool)

kC4ReplicatorProxyAuth

#define kC4ReplicatorProxyAuth   "auth"

Proxy auth (Dict); see above.

kC4ReplicatorProxyHost

#define kC4ReplicatorProxyHost   "host"

Proxy hostname (string)

kC4ReplicatorProxyPort

#define kC4ReplicatorProxyPort   "port"

Proxy port number (integer)

kC4ReplicatorProxyType

#define kC4ReplicatorProxyType   "type"

Proxy type; see [4] (string)

kC4SocketOptionNetworkInterface

#define kC4SocketOptionNetworkInterface    "networkInterface"

Specific network interface (name or IP address) used for connecting to the remote server.

kC4SocketOptionWSProtocols

#define kC4SocketOptionWSProtocols   "WS-Protocols"

Sec-WebSocket-Protocol header value.

Typedef Documentation

C4ReplicatorBlobProgressCallback

typedef void(* C4ReplicatorBlobProgressCallback) (C4Replicator *, bool pushing, C4CollectionSpec collectionSpec, C4String docID, C4String docProperty, C4BlobKey blobKey, uint64_t bytesComplete, uint64_t bytesTotal, C4Error error, void *context)

Callback a client can register, to hear about the status of blobs.

C4ReplicatorDocumentsEndedCallback

typedef void(* C4ReplicatorDocumentsEndedCallback) (C4Replicator *, bool pushing, size_t numDocs, const C4DocumentEnded *docs[], void *context)

Callback a client can register, to hear about the replication status of documents.

By default, only errors will be reported via this callback. To also receive callbacks for successfully completed documents, set the kC4ReplicatorOptionProgressLevel option to a value greater than zero.

C4ReplicatorPropertyDecryptionCallback

typedef void* C4ReplicatorPropertyDecryptionCallback

C4ReplicatorPropertyEncryptionCallback

typedef void* C4ReplicatorPropertyEncryptionCallback

C4ReplicatorStatusChangedCallback

typedef void(* C4ReplicatorStatusChangedCallback) (C4Replicator *, C4ReplicatorStatus, void *context)

Callback a client can register, to get progress information.

This will be called on arbitrary background threads, and should not block.

C4ReplicatorValidationFunction

typedef bool(* C4ReplicatorValidationFunction) (C4CollectionSpec collectionSpec, C4String docID, C4String revID, C4RevisionFlags, FLDict body, void *context)

Callback that can choose to reject an incoming pulled revision, or stop a local revision from being pushed, by returning false.

(Note: In the case of an incoming revision, no flags other than 'deletion' and 'hasAttachments' will be set.)

Enumeration Type Documentation

C4ReplicatorActivityLevel

enum C4ReplicatorActivityLevel : int32_t

Enumerator
kC4Stopped	Finished, or got a fatal error.
kC4Offline	Connection failed, but waiting to retry. *‍/.
kC4Connecting	Connection is in progress.
kC4Idle	Continuous replicator has caught up and is waiting for changes.
kC4Busy	Connected and actively working.
kC4Stopping	Stopping or going offline.

C4ReplicatorMode

enum C4ReplicatorMode : int32_t

Enumerator
kC4Disabled
kC4Passive
kC4OneShot
kC4Continuous

C4ReplicatorProgressLevel

enum C4ReplicatorProgressLevel : int32_t

Enumerator
kC4ReplProgressOverall	Callback about completion and estimated total (C4ReplicatorStatusChangedCallback)
kC4ReplProgressPerDocument	Callback for every document replicated (C4ReplicatorDocumentsEndedCallback)
kC4ReplProgressPerAttachment	Callback for every document and attachment replicated (C4ReplicatorBlobProgressCallback)

C4ReplicatorStatusFlags

enum C4ReplicatorStatusFlags : int32_t

Enumerator
kC4WillRetry	If true, will automatically reconnect when offline.
kC4HostReachable	If false, it's not possible to connect to the host.
kC4Suspended	If true, will not connect until unsuspended.

Function Documentation

c4address_fromURL()

NODISCARD CBL_CORE_API bool c4address_fromURL	(	C4String	url,
		C4Address *	address,
		C4String *	dbName )

A simple URL parser that populates a C4Address from a URL string.

The fields of the address will point inside the url string.

Note

This function is thread-safe.

Parameters

url	The URL to be parsed.
address	On sucess, the fields of the struct this points to will be populated with the address components. This that are slices will point into the appropriate substrings of url.
dbName	If non-NULL, then on success this slice will point to the last path component of url; address->path will not include this component.

Returns

True on success, false on failure.

c4address_toURL()

CBL_CORE_API C4StringResult c4address_toURL

(

C4Address

address

)

Converts a C4Address to a URL.

c4db_clearCookies()

CBL_CORE_API void c4db_clearCookies

(

C4Database *

db

)

Removes all cookies from the database's cookie store.

Note

The caller must use a lock for Database when this function is called.

c4db_getCookies()

CBL_CORE_API C4StringResult c4db_getCookies	(	C4Database *	db,
		C4Address	request,
		C4Error *	error )

Locates any saved HTTP cookies relevant to the given request, and returns them as a string that can be used as the value of a "Cookie:" header.

Note

The caller must use a lock for Database when this function is called.

c4db_setCookie()

NODISCARD CBL_CORE_API bool c4db_setCookie	(	C4Database *	db,
		C4String	setCookieHeader,
		C4String	fromHost,
		C4String	fromPath,
		bool	acceptParentDomain,
		C4Error *	outError )

Takes the value of a "Set-Cookie:" header, received from the given host, from an HTTP request with the given path, and saves the cookie into the database's cookie store.

(Persistent cookies are saved as metadata in the database file until they expire. Session cookies are kept in memory, until the last C4Database handle to the given database is closed.)

Note

The caller must use a lock for Database when this function is called.

Parameters

db	The C4Databaser instance.
setCookieHeader	The "Set-Cookie" header.
fromHost	The host address of the request.
fromPath	The path of the request.
acceptParentDomain	Whether to allow the "Domain" property of the cookie to be a parent domain of the host address. It should match the option, kC4ReplicatorOptionAcceptParentDomainCookies, in C4ReplicatorParameters.
outError	Records error information, if any.

Returns

true if the cookie is successfully saved..

c4repl_getPeerTLSCertificate()

NODISCARD CBL_CORE_API C4Cert * c4repl_getPeerTLSCertificate	(	C4Replicator *	repl,
		C4Error *	outErr )

Gets the TLS certificate, if any, that was sent from the remote server (NOTE: Only functions when using BuiltInWebSocket)

Note

This function is thread-safe.

c4repl_getPendingDocIDs()

CBL_CORE_API C4SliceResult c4repl_getPendingDocIDs	(	C4Replicator *	repl,
		C4CollectionSpec	spec,
		C4Error *	outErr )

Gets a fleece encoded list of IDs of documents who have revisions pending push.

This API is a snapshot and results may change between the time the call was made and the time the call returns.

Note

This function is thread-safe.

Parameters

repl	The C4Replicator instance.
spec	The collection spec
outErr	On failure, error information will be written here if non-NULL.

Returns

A fleece encoded array of document IDs, each of which has one or more pending revisions. If none are pending, nullslice is returned (note that an error condition will return nullslice with the outErr code set to non-zero)

c4repl_getResponseHeaders()

CBL_CORE_API C4Slice c4repl_getResponseHeaders

(

C4Replicator *

repl

)

Returns the HTTP response headers as a Fleece-encoded dictionary.

Note

This function is thread-safe.

c4repl_getStatus()

CBL_CORE_API C4ReplicatorStatus c4repl_getStatus

(

C4Replicator *

repl

)

Returns the current state of a replicator.

Note

This function is thread-safe.

c4repl_isDocumentPending()

NODISCARD CBL_CORE_API bool c4repl_isDocumentPending	(	C4Replicator *	repl,
		C4String	docID,
		C4CollectionSpec	spec,
		C4Error *	outErr )

Checks if the document with the given ID has revisions pending push.

This API is a snapshot and results may change between the time the call was made and the time the call returns.

Note

This function is thread-safe.

Parameters

repl	The C4Replicator instance.
docID	The ID of the document to check
spec	The collection the docID belongs to.
outErr	On failure, error information will be written here if non-NULL.

Returns

true if the document has one or more revisions pending, false otherwise (note that an error condition will return false with the outErr code set to non-zero)

c4repl_isValidDatabaseName()

CBL_CORE_API bool c4repl_isValidDatabaseName

(

C4String

dbName

)

Checks whether a database name is valid, for purposes of appearing in a replication URL.

c4repl_isValidRemote()

NODISCARD CBL_CORE_API bool c4repl_isValidRemote	(	C4Address	remoteAddress,
		C4String	remoteDatabaseName,
		C4Error *	outError )

Checks whether the destination of a replication is valid.

(c4repl_new makes the same checks; this function is exposed so CBL can fail sooner.)

c4repl_new()

NODISCARD CBL_CORE_API C4Replicator * c4repl_new	(	C4Database *	db,
		C4Address	remoteAddress,
		C4String	remoteDatabaseName,
		C4ReplicatorParameters	params,
		C4String	logPrefix,
		C4Error *	outError )

Creates a new networked replicator.

Note

The caller must use a lock for Database when this function is called.

Parameters

db	The local database.
remoteAddress	The address of the remote server.
remoteDatabaseName	The name of the database at the remote address.
params	Replication parameters (see above.)
logPrefix	prefix to the loggingClassName of returned C4Replicator.
outError	Error, if replication can't be created.

Returns

The newly created replicator, or NULL on error.

c4repl_newWithSocket()

NODISCARD CBL_CORE_API C4Replicator * c4repl_newWithSocket	(	C4Database *	db,
		C4Socket *	openSocket,
		C4ReplicatorParameters	params,
		C4String	logPrefix,
		C4Error *	outError )

Creates a new replicator from an already-open C4Socket.

This is for use by listeners that accept incoming connections, wrap them by calling c4socket_fromNative(), then start a passive replication to service them.

Note

The caller must use a lock for Database when this function is called.

Parameters

db	The local database.
openSocket	An already-created C4Socket.
params	Replication parameters. Will usually use kC4Passive modes.
logPrefix	prefix to the loggingClassName of returned C4Replicator.
outError	Error, if replication can't be created.

Returns

The newly created replicator, or NULL on error.

c4repl_retry()

NODISCARD CBL_CORE_API bool c4repl_retry	(	C4Replicator *	repl,
		C4Error *	outError )

Tells a replicator that's in the offline state to reconnect immediately.

Note

This function is thread-safe.

Parameters

repl	The replicator.
outError	On failure, error information is stored here.

Returns

True if the replicator will reconnect, false if it won't.

c4repl_setHostReachable()

CBL_CORE_API void c4repl_setHostReachable	(	C4Replicator *	repl,
		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.

Note

This function is thread-safe.

c4repl_setOptions()

CBL_CORE_API void c4repl_setOptions	(	C4Replicator *	repl,
		C4Slice	optionsDictFleece )

Sets the replicator's options dictionary.

The changes will take effect next time the replicator connects.

Note

This function is thread-safe.

c4repl_setProgressLevel()

NODISCARD CBL_CORE_API bool c4repl_setProgressLevel	(	C4Replicator *	repl,
		C4ReplicatorProgressLevel	level,
		C4Error *	outErr )

Sets the progress level of the replicator, indicating what information should be provided via callback.

Note

The caller must use a lock for Replicator when this function is called.

Parameters

repl	The C4Replicator instance.
level	The progress level to set on the replicator
outErr	Records error information, if any.

Returns

true if the progress level was set, false if there was an error.

c4repl_setSuspended()

CBL_CORE_API void c4repl_setSuspended	(	C4Replicator *	repl,
		bool	suspended )

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

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.

Note

This function is thread-safe.

c4repl_start()

CBL_CORE_API void c4repl_start	(	C4Replicator *	repl,
		bool	reset )

Tells a replicator to start.

Ignored if it's not in the Stopped state.

Note

This function is thread-safe.

Do not call this function while a transaction is open on the same database as it can deadlock when repl tries to acquire the database.

Parameters

repl	The C4Replicator instance.
reset	If true, the replicator will reset its checkpoint and start replication from the beginning

c4repl_stop()

CBL_CORE_API void c4repl_stop

(

C4Replicator *

repl

)

Tells a replicator to stop.

Ignored if in the Stopped state.

Note

This function is thread-safe.

Variable Documentation

kC4ReplicatorActivityLevelNames

CBL_CORE_API const char* const kC4ReplicatorActivityLevelNames[6]

extern

For convenience, an array of C strings naming the C4ReplicatorActivityLevel values.