Couchbase Lite
Objective-C API for iOS and Mac OS
Instance Methods | Class Methods | Properties | List of all members
CBLReplication Class Reference

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

#import <CBLReplication.h>

Inheritance diagram for CBLReplication:

Instance Methods

(BOOL) - registerFacebookToken:forEmailAddress:
 Registers a Facebook login token that will be used on the next login to the remote server. More...
 
(BOOL) - registerPersonaAssertion:
 Registers a Persona 'assertion' (ID verification) string that will be used on the next login to the remote server. More...
 
(void) - start
 Starts the replication, asynchronously. More...
 
(void) - stop
 Stops replication, asynchronously. More...
 
(void) - restart
 Restarts a running replication. More...
 

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

CBLDatabaselocalDatabase
 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...
 
NSDictionary * filterParams
 Parameters to pass to the filter function. More...
 
NSArray * channels
 List of Sync Gateway channel names to filter by; a nil value means no filtering, i.e. More...
 
NSArray * documentIDs
 Sets the documents to specify as part of the replication. More...
 
NSDictionary * headers
 Extra HTTP headers to send in all requests to the remote server. More...
 
NSString * network
 Specifies which class of network the replication will operate over. More...
 
NSDictionary * customProperties
 An optional JSON-compatible dictionary of extra properties for the replicator. More...
 
NSURLCredential * credential
 The credential (generally username+password) to use to authenticate to the remote database. More...
 
NSDictionary * OAuth
 OAuth parameters that the replicator should use when authenticating to the remote database. More...
 
NSString * facebookEmailAddress
 Email address for login with Facebook credentials. More...
 
NSURL * personaOrigin
 The base URL of the remote server, for use as the "origin" parameter when requesting Persona or Facebook authentication. More...
 
NSString * personaEmailAddress
 Email address for remote login with Persona (aka BrowserID). 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...
 

Detailed Description

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

Replications can be one-shot or continuous.

Method Documentation

- (BOOL) registerFacebookToken: (NSString *)  token
forEmailAddress: (NSString *)  email 

Registers a Facebook login token that will be used on the next login to the remote server.

This also sets facebookEmailAddress. For security reasons the token is not stored in the replication document, but instead kept in an in-memory registry private to the Facebook authorizer. On login the token is sent to the server, and the server will respond with a session cookie. After that the token isn't needed again until the session expires. At that point you'll need to recover or regenerate the token and register it again.

- (BOOL) registerPersonaAssertion: (NSString *)  assertion

Registers a Persona 'assertion' (ID verification) string that will be used on the next login to the remote server.

This also sets personaEmailAddress. Note: An assertion is a type of certificate and typically has a very short lifespan (like, a few minutes.) For this reason it's not stored in the replication document, but instead kept in an in-memory registry private to the Persona authorizer. You should initiate a replication immediately after registering the assertion, so that the replicator engine can use it to authenticate before it expires. After that, the replicator will have a login session cookie that should last significantly longer before needing to be renewed.

+ (void) setAnchorCerts: (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
certsAn 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.
onlyTheseIf 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.)
- (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.

- (void) stop

Stops replication, asynchronously.

Has no effect if the replication is not running.

- (void) restart

Restarts a running replication.

Has no effect if the replication is not running.

Property Documentation

- (CBLDatabase*) localDatabase
readnonatomicassign

The local database being replicated to/from.

- (NSURL*) remoteURL
readnonatomicassign

The URL of the remote database.

- (BOOL) pull
readnonatomicassign

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

- (BOOL) createTarget
readwritenonatomicassign

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

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

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

- (NSDictionary*) filterParams
readwritenonatomiccopy

Parameters to pass to the filter function.

Should map strings to strings.

- (NSArray*) channels
readwritenonatomiccopy

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

- (NSArray*) documentIDs
readwriteatomiccopy

Sets the documents to specify as part of the replication.

- (NSDictionary*) headers
readwritenonatomiccopy

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

Should map strings (header names) to strings.

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

- (NSDictionary*) customProperties
readwritenonatomiccopy

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

- (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 NSURLCredentialStore, which is a wrapper around the Keychain.

- (NSDictionary*) 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".

- (NSString*) facebookEmailAddress
readwritenonatomiccopy

Email address for login with Facebook credentials.

In addition to this, you also need to get a token from Facebook's servers, which you then pass to -registerFacebookToken:forEmailAddress.

- (NSURL*) personaOrigin
readatomicassign

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

- (NSString*) personaEmailAddress
readwritenonatomiccopy

Email address for remote login with Persona (aka BrowserID).

In addition to this, you also need to go through the Persona protocol to get a signed assertion, which you then pass to the -registerPersonaAssertion: method.)

- (CBLReplicationStatus) status
readnonatomicassign

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

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

- (NSError*) lastError
readnonatomicretain

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

- (unsigned) completedChangesCount
readnonatomicassign

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

- (unsigned) changesCount
readnonatomicassign

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


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