Detailed Description

A 'push' or 'pull' replication between a local and a remote database.

Replications can be one-shot or continuous.

Inheritance diagram for CBLReplication:

Instance Methods
()	- CBLArrayOf
	List of Sync Gateway channel names to filter by; a nil value means no filtering, i.e. More...

()	- CBLArrayOf
	Sets the documents to specify as part of the replication. More...

()	- CBLDictOf
	Extra HTTP headers to send in all requests to the remote server. More...

(void)	- setCookieNamed:withValue:path:expirationDate:secure:
	Registers an HTTP cookie that will be sent to the remote server along with the replication's HTTP requests. More...

(void)	- deleteCookieNamed:
	Deletes the named cookie from this replication's cookie storage. More...

(BOOL)	- clearAuthenticationStores:
	Deletes any persistent credentials (passwords, auth tokens...) associated with this replication's CBLAuthenticator. More...

(void)	- start
	Starts the replication, asynchronously. More...

(void)	- stop
	Stops replication, asynchronously. More...

(void)	- restart
	Restarts a running replication. More...

(BOOL)	- isDocumentPending:
	Returns YES if a document has local changes that this replication will push to its server, but hasn't yet. More...

(NSProgress *)	- downloadAttachment:
	Starts an asynchronous download of an attachment that was skipped in a pull replication. More...

(instancetype)	- NS_UNAVAILABLE

Class Methods
(void)	+ setAnchorCerts:onlyThese:
	Adds additional SSL root certificates to be trusted by the replicator, or entirely overrides the OS's default list of trusted root certs. More...

Properties
CBLDatabase *	localDatabase
	The local database being replicated to/from. More...

NSURL *	remoteURL
	The URL of the remote database. More...

BOOL	pull
	Does the replication pull from (as opposed to push to) the target? More...

BOOL	createTarget
	Should the target database be created if it doesn't already exist? (Defaults to NO). More...

bool	continuous
	Should the replication operate continuously? (Defaults to NO). More...

NSString *	filter
	Name of an optional filter function to run on the source server. More...

CBLJSONDict *	filterParams
	Parameters to pass to the filter function. More...

BOOL	downloadsAttachments
	Should attachments be downloaded automatically along with documents? Defaults to YES; if you set it to NO you can later download individual attachments by calling -downloadAttachment:. More...

NSString *	network
	Specifies which class of network the replication will operate over. More...

CBLJSONDict *	customProperties
	An optional JSON-compatible dictionary of extra properties for the replicator. More...

id< CBLAuthenticator >	authenticator
	An object that knows how to authenticate with a remote server. More...

NSURLCredential *	credential
	The credential (generally username+password) to use to authenticate to the remote database. More...

NSString *	username
	The server user name that the authenticator has logged in as, if known. More...

CBLJSONDict *	OAuth
	OAuth parameters that the replicator should use when authenticating to the remote database. More...

NSURL *	personaOrigin
	The base URL of the remote server, for use as the "origin" parameter when requesting Persona or Facebook authentication. More...

SecCertificateRef	serverCertificate
	The server's SSL certificate. More...

BOOL	suspended
	Suspends/resumes a replication. More...

CBLReplicationStatus	status
	The replication's current state, one of {stopped, offline, idle, active}. More...

BOOL	running
	YES while the replication is running, NO if it's stopped. More...

NSError *	lastError
	The error status of the replication, or nil if there have not been any errors since it started. More...

unsigned	completedChangesCount
	The number of completed changes processed, if the task is active, else 0 (observable). More...

unsigned	changesCount
	The total number of changes to be processed, if the task is active, else 0 (observable). More...

NSSet *	pendingDocumentIDs
	The IDs of documents that have local changes that have not yet been pushed to the server by this replication. More...

CBLPropertiesTransformationBlock	propertiesTransformationBlock
	Optional callback for transforming document bodies during replication; can be used to encrypt documents stored on the remote server, for example. More...

Method Documentation

◆ CBLArrayOf() [1/2]

- CBLArrayOf (NSString *)

List of Sync Gateway channel names to filter by; a nil value means no filtering, i.e.

all available channels will be synced. Only valid for pull replications whose source database is on a Couchbase Sync Gateway server. (This is a convenience that just reads or changes the values of .filter and .query_params.)

◆ CBLArrayOf() [2/2]

- CBLArrayOf (NSString *)

Sets the documents to specify as part of the replication.

◆ CBLDictOf()

- CBLDictOf		(NSString *)
		(NSString *)

Extra HTTP headers to send in all requests to the remote server.

Should map strings (header names) to strings.

◆ setCookieNamed:withValue:path:expirationDate:secure:()

- (void) setCookieNamed:	(NSString *)	name
withValue:	(NSString *)	value
path:	(nullable NSString *)	path
expirationDate:	(nullable NSDate *)	expirationDate
secure:	(BOOL)	secure

Registers an HTTP cookie that will be sent to the remote server along with the replication's HTTP requests.

This is useful if you've obtained a session cookie through some external means. The cookie will be saved persistently until its expirationDate passes; or if that date is nil, the cookie will only be associated with this replication object.

The parameters have the same meanings as in the NSHTTPCookie API. If the path is nil, the path of this replication's URL is used.

The replicator does not use the standard shared NSHTTPCookieStorage, so registering a cookie through that will have no effect. This is because each replication has independent authentication and may need to send different cookies.

◆ deleteCookieNamed:()

- (void) deleteCookieNamed: (NSString *) name

Deletes the named cookie from this replication's cookie storage.

◆ clearAuthenticationStores:()

- (BOOL) clearAuthenticationStores: (NSError **) outError

Deletes any persistent credentials (passwords, auth tokens...) associated with this replication's CBLAuthenticator.

Also removes session cookies from the cookie store.

◆ setAnchorCerts:onlyThese:()

+ (void) setAnchorCerts:	(nullable NSArray *)	certs
onlyThese:	(BOOL)	onlyThese

Adds additional SSL root certificates to be trusted by the replicator, or entirely overrides the OS's default list of trusted root certs.

Parameters

certs	An array of SecCertificateRefs of root certs that should be trusted. Most often these will be self-signed certs, but they might also be the roots of nonstandard CAs.
onlyThese	If NO, the given certs are appended to the system's built-in list of trusted root certs; if YES, it replaces them (so only the given certs will be trusted.)

◆ start()

- (void) start

Starts the replication, asynchronously.

Has no effect if the replication is already running. You can monitor its progress by observing the kCBLReplicationChangeNotification it sends, or by using KVO to observe its .running, .status, .error, .total and .completed properties.

◆ stop()

- (void) stop

Stops replication, asynchronously.

Has no effect if the replication is not running.

◆ restart()

- (void) restart

Restarts a running replication.

Has no effect if the replication is not running.

◆ isDocumentPending:()

- (BOOL) isDocumentPending: (CBLDocument *) doc

Returns YES if a document has local changes that this replication will push to its server, but hasn't yet.

This only considers documents that this replication would push: it returns NO for a document that isn't matched by its filter or documentIDs, even if that document has local changes.

◆ downloadAttachment:()

- (NSProgress*) downloadAttachment: (CBLAttachment *) attachment

Starts an asynchronous download of an attachment that was skipped in a pull replication.

Parameters

attachment The attachment to download.

Returns: An NSProgress object that will be updated to report the progress of the download. You can use Key-Value Observing to observe its fractionCompleted property. (Note: observer callbacks will be issued on a background thread!) You can cancel the download by calling its -cancel method.

◆ NS_UNAVAILABLE()

- (instancetype) NS_UNAVAILABLE

Property Documentation

◆ localDatabase

- (CBLDatabase*) localDatabase

readnonatomicassign

The local database being replicated to/from.

◆ remoteURL

- (NSURL*) remoteURL

readnonatomicassign

The URL of the remote database.

◆ pull

- (BOOL) pull

readnonatomicassign

Does the replication pull from (as opposed to push to) the target?

◆ createTarget

- (BOOL) createTarget

readwritenonatomicassign

Should the target database be created if it doesn't already exist? (Defaults to NO).

◆ continuous

- (bool) continuous

readwritenonatomicassign

Should the replication operate continuously? (Defaults to NO).

A continuous replication keeps running (with 'idle' status) after updating the target database. It monitors the source database and copies new revisions as soon as they're available. Continuous replications keep running until the app quits or they're stopped.

◆ filter

- (NSString*) filter

readwritenonatomiccopy

Name of an optional filter function to run on the source server.

Only documents for which the function returns true are replicated. For a pull replication, the name looks like "designdocname/filtername". For a push replication, use the name under which you registered the filter with the CBLDatabase.

◆ filterParams

- (CBLJSONDict*) filterParams

readwritenonatomiccopy

Parameters to pass to the filter function.

Should map strings to strings.

◆ downloadsAttachments

- (BOOL) downloadsAttachments

readwritenonatomicassign

Should attachments be downloaded automatically along with documents? Defaults to YES; if you set it to NO you can later download individual attachments by calling -downloadAttachment:.

◆ network

- (NSString*) network

readwritenonatomiccopy

Specifies which class of network the replication will operate over.

Default value is nil, which means replicate over all networks. Set to "WiFi" (or "!Cell") to replicate only over WiFi, or to "Cell" (or "!WiFi") to replicate only over cellular.

◆ customProperties

- (CBLJSONDict*) customProperties

readwritenonatomiccopy

An optional JSON-compatible dictionary of extra properties for the replicator.

◆ authenticator

- (id<CBLAuthenticator>) authenticator

readwritenonatomicstrong

An object that knows how to authenticate with a remote server.

CBLAuthenticator is an opaque protocol; instances can be created by calling the factory methods of the class of the same name.

◆ credential

- (NSURLCredential*) credential

readwritenonatomicstrong

The credential (generally username+password) to use to authenticate to the remote database.

This can either come from the URL itself (if it's of the form "http://user:pass@example.com") or be stored in the NSURLCredentialStorage, which is a wrapper around the Keychain.

◆ username

- (NSString*) username

readnonatomicassign

The server user name that the authenticator has logged in as, if known.

Observable.

◆ OAuth

- (CBLJSONDict*) OAuth

readwritenonatomiccopy

OAuth parameters that the replicator should use when authenticating to the remote database.

Keys in the dictionary should be "consumer_key", "consumer_secret", "token", "token_secret", and optionally "signature_method".

◆ personaOrigin

- (NSURL*) personaOrigin

readatomicassign

The base URL of the remote server, for use as the "origin" parameter when requesting Persona or Facebook authentication.

◆ serverCertificate

- (SecCertificateRef) serverCertificate

readatomicassign

The server's SSL certificate.

This will be NULL until the first HTTPS response is received from the server.

◆ suspended

- (BOOL) suspended

readwriteatomic

Suspends/resumes a replication.

On iOS a replication will suspend itself when the app goes into the background, and resume when the app is re-activated. If your app receives a push notification while suspended and needs to run the replication to download new data, your handler should set suspended to NO to resume replication, and then set the property back to YES when it's done.

◆ status

- (CBLReplicationStatus) status

readnonatomicassign

The replication's current state, one of {stopped, offline, idle, active}.

◆ running

- (BOOL) running

readnonatomicassign

YES while the replication is running, NO if it's stopped.

Note that a continuous replication never actually stops; it only goes idle waiting for new data to appear.

◆ lastError

- (NSError*) lastError

readnonatomicstrong

The error status of the replication, or nil if there have not been any errors since it started.

◆ completedChangesCount

- (unsigned) completedChangesCount

readnonatomicassign

The number of completed changes processed, if the task is active, else 0 (observable).

◆ changesCount

- (unsigned) changesCount

readnonatomicassign

The total number of changes to be processed, if the task is active, else 0 (observable).

◆ pendingDocumentIDs

- (NSSet*) pendingDocumentIDs

readatomicassign

The IDs of documents that have local changes that have not yet been pushed to the server by this replication.

This only considers documents that this replication would push: documents that aren't matched by its filter or documentIDs (if any) are ignored. If the replication hasn't started yet, or if it's encountered an error, or if it's not a push replication at all, the value of this property is nil.

◆ propertiesTransformationBlock

- (CBLPropertiesTransformationBlock) propertiesTransformationBlock

readwriteatomicstrong

Optional callback for transforming document bodies during replication; can be used to encrypt documents stored on the remote server, for example.

In a push replication, the block is called with document properties from the local database, and the transformed properties are what will be uploaded to the server. In a pull replication, the block is called with document properties downloaded from the server, and the transformed properties are what will be stored in the local database. The block takes an NSDictionary containing the document's properties (including the "_id" and "_rev" metadata), and returns a dictionary of transformed properties. It may return the input dictionary if it has no changes to make. The transformation MUST preserve the values of any keys whose names begin with an underscore ("_")! The block will be called on the background replicator thread, NOT on the CBLReplication's thread, so it shouldn't directly access any Couchbase Lite objects.

Provided by category CBLReplication(Transformation).

The documentation for this class was generated from the following file:

CBLReplication.h

Detailed Description

Instance Methods

Class Methods

Properties

Method Documentation

◆ CBLArrayOf() [1/2]

◆ CBLArrayOf() [2/2]

◆ CBLDictOf()

◆ setCookieNamed:withValue:path:expirationDate:secure:()

◆ deleteCookieNamed:()

◆ clearAuthenticationStores:()

◆ setAnchorCerts:onlyThese:()

◆ start()

◆ stop()

◆ restart()

◆ isDocumentPending:()

◆ downloadAttachment:()

◆ NS_UNAVAILABLE()

Property Documentation

◆ localDatabase

◆ remoteURL

◆ pull

◆ createTarget

◆ continuous

◆ filter

◆ filterParams

◆ downloadsAttachments

◆ network

◆ customProperties

◆ authenticator

◆ credential

◆ username

◆ OAuth

◆ personaOrigin

◆ serverCertificate

◆ suspended

◆ status

◆ running

◆ lastError

◆ completedChangesCount

◆ changesCount

◆ pendingDocumentIDs

◆ propertiesTransformationBlock