Couchbase Lite C
Couchbase Lite C API
CBLReplicator.h
Go to the documentation of this file.
1//
2// CBLReplicator.h
3//
4// Copyright (c) 2018 Couchbase, Inc All rights reserved.
5//
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17//
18
19#pragma once
20#include "CBLBase.h"
21
23
34
36typedef struct CBLEndpoint CBLEndpoint;
37
49 CBLError* _cbl_nullable outError) CBLAPI;
50
51#ifdef COUCHBASE_ENTERPRISE
55#endif
56
59
60
63
67
72
75
76
78typedef CBL_ENUM(uint8_t, CBLReplicatorType) {
82};
83
84
86typedef CBL_OPTIONS(unsigned, CBLDocumentFlags) {
89};
90
91
100typedef bool (*CBLReplicationFilter)(void* _cbl_nullable context,
101 CBLDocument* document,
102 CBLDocumentFlags flags);
103
127 FLString documentID,
128 const CBLDocument* _cbl_nullable localDocument,
129 const CBLDocument* _cbl_nullable remoteDocument);
130
133
134
136typedef CBL_ENUM(uint8_t, CBLProxyType) {
139};
140
141
143typedef struct {
146 uint16_t port;
150
151#ifdef COUCHBASE_ENTERPRISE
152
176 void* context,
177 FLString documentID,
178 FLDict properties,
179 FLString keyPath,
180 FLSlice input,
181 FLStringResult* algorithm,
182 FLStringResult* kid,
183 CBLError* error
184);
185
211 void* context,
212 FLString documentID,
213 FLDict properties,
214 FLString keyPath,
215 FLSlice input,
216 FLString algorithm,
217 FLString kid,
218 CBLError* error
219);
220
243 void* context,
244 FLString scope,
245 FLString collection,
246 FLString documentID,
247 FLDict properties,
248 FLString keyPath,
249 FLSlice input,
250 FLStringResult* algorithm,
251 FLStringResult* kid,
252 CBLError* error
253);
254
279 void* context,
280 FLString scope,
281 FLString collection,
282 FLString documentID,
283 FLDict properties,
284 FLString keyPath,
285 FLSlice input,
286 FLString algorithm,
287 FLString kid,
288 CBLError* error
289);
290
291#endif
292
294typedef struct {
296
298
301
307
309typedef struct {
316
317 //-- Types:
318
321
324
325 //-- Auto Purge:
326
336
337 //-- Retry Logic:
338
343 unsigned maxAttempts;
344
348
349 //-- WebSocket:
350
353 unsigned heartbeat;
354
355#ifdef __CBL_REPLICATOR_NETWORK_INTERFACE__
360 FLString networkInterface;
361#endif
362
363 //-- HTTP settings:
364
368
369 //-- TLS settings:
370
375
376 //-- Filtering:
377
383
388
393
398
399 //-- Conflict Resolver:
400
405
406 //-- Context:
408
409#ifdef COUCHBASE_ENTERPRISE
410 //-- Property Encryption
415
420
423
426#endif
427
430
433
434 //-- Advanced HTTP settings:
435
446
447
455
459 CBLError* _cbl_nullable outError) CBLAPI;
460
463
473 bool resetCheckpoint) CBLAPI;
474
479
486 bool reachable) CBLAPI;
487
494
510
515typedef struct {
516 float complete;
517 uint64_t documentCount;
519
521typedef struct {
526
529
548
560 FLString docID,
561 CBLError* _cbl_nullable outError) CBLAPI;
562
573 const CBLCollection* collection,
574 CBLError* _cbl_nullable outError) CBLAPI;
575
585 FLString docID,
586 const CBLCollection* collection,
587 CBLError* _cbl_nullable outError) CBLAPI;
588
596typedef void (*CBLReplicatorChangeListener)(void* _cbl_nullable context,
597 CBLReplicator *replicator,
598 const CBLReplicatorStatus *status);
599
604 void* _cbl_nullable context) CBLAPI;
605
606
608typedef struct {
615
625typedef void (*CBLDocumentReplicationListener)(void *context,
626 CBLReplicator *replicator,
627 bool isPush,
628 unsigned numDocuments,
629 const CBLReplicatedDocument* documents);
630
635 void* _cbl_nullable context) CBLAPI;
636
#define CBL_OPTIONS(_type, _name)
Definition: CBL_Compat.h:63
#define CBLAPI
Definition: CBL_Compat.h:104
#define _cbl_nullable
Definition: CBL_Compat.h:92
#define CBL_CAPI_BEGIN
Definition: CBL_Compat.h:105
#define CBL_CAPI_END
Definition: CBL_Compat.h:106
#define CBL_PUBLIC
Definition: CBL_Compat.h:123
#define CBL_ENUM(_type, _name)
Definition: CBL_Compat.h:62
#define _cbl_warn_unused
Definition: CBL_Compat.h:40
struct CBLCollection CBLCollection
A collection, a document container.
Definition: CBLBase.h:194
struct CBLDatabase CBLDatabase
A connection to an open database.
Definition: CBLBase.h:182
struct CBLDocument CBLDocument
An in-memory copy of a document.
Definition: CBLBase.h:203
struct CBLListenerToken CBLListenerToken
An opaque 'cookie' representing a registered listener callback.
Definition: CBLBase.h:281
#define CBL_REFCOUNTED(TYPE, NAME)
Definition: CBLBase.h:170
CBLProxyType
Types of proxy servers, for CBLProxySettings.
Definition: CBLReplicator.h:136
struct CBLAuthenticator CBLAuthenticator
An opaque object representing authentication credentials for a remote server.
Definition: CBLReplicator.h:62
_cbl_warn_unused CBLAuthenticator * CBLAuth_CreateSession(FLString sessionID, FLString cookieName)
Creates an authenticator using a Couchbase Sync Gateway login session identifier, and optionally a co...
struct CBLEndpoint CBLEndpoint
An opaque object representing the location of a database to replicate with.
Definition: CBLReplicator.h:36
bool(* CBLReplicationFilter)(void *_cbl_nullable context, CBLDocument *document, CBLDocumentFlags flags)
A callback that can decide whether a particular document should be pushed or pulled.
Definition: CBLReplicator.h:100
void CBLReplicator_Start(CBLReplicator *replicator, bool resetCheckpoint)
Starts a replicator, asynchronously.
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 of the default collection pul...
Definition: CBLReplicator.h:210
_cbl_warn_unused CBLAuthenticator * CBLAuth_CreatePassword(FLString username, FLString password)
Creates an authenticator for HTTP Basic (username/password) auth.
FLDict _cbl_nullable CBLReplicator_PendingDocumentIDs2(CBLReplicator *, const CBLCollection *collection, CBLError *_cbl_nullable outError)
Indicates which documents in the given collection have local changes that have not yet been pushed to...
bool CBLReplicator_IsDocumentPending(CBLReplicator *repl, FLString docID, CBLError *_cbl_nullable outError)
Indicates whether the document in the default collection with the given ID has local changes that hav...
FLSliceResult(* CBLDocumentPropertyEncryptor)(void *context, FLString scope, FLString collection, 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.
Definition: CBLReplicator.h:242
CBL_PUBLIC const FLString kCBLAuthDefaultCookieName
The name of the HTTP cookie used by Sync Gateway to store session keys.
void CBLReplicator_Stop(CBLReplicator *)
Stops a running replicator, asynchronously.
struct CBLReplicator CBLReplicator
A background task that syncs a CBLDatabase with a remote server or peer.
Definition: CBLBase.h:234
_cbl_warn_unused CBLReplicator *_cbl_nullable CBLReplicator_Create(const CBLReplicatorConfiguration *, CBLError *_cbl_nullable outError)
Creates a replicator with the given configuration.
_cbl_warn_unused FLDict _cbl_nullable CBLReplicator_PendingDocumentIDs(CBLReplicator *, CBLError *_cbl_nullable outError)
Indicates which documents in the default collection have local changes that have not yet been pushed ...
void(* CBLReplicatorChangeListener)(void *_cbl_nullable context, CBLReplicator *replicator, const CBLReplicatorStatus *status)
A callback that notifies you when the replicator's status changes.
Definition: CBLReplicator.h:596
CBLReplicatorStatus CBLReplicator_Status(CBLReplicator *)
Returns the replicator's current status.
void CBLEndpoint_Free(CBLEndpoint *_cbl_nullable)
Frees a CBLEndpoint object.
void(* CBLDocumentReplicationListener)(void *context, CBLReplicator *replicator, bool isPush, unsigned numDocuments, const CBLReplicatedDocument *documents)
A callback that notifies you when documents are replicated.
Definition: CBLReplicator.h:625
CBL_PUBLIC const CBLConflictResolver CBLDefaultConflictResolver
Default conflict resolver.
CBLReplicatorActivityLevel
The possible states a replicator can be in during its lifecycle.
Definition: CBLReplicator.h:503
bool CBLReplicator_IsDocumentPending2(CBLReplicator *repl, FLString docID, const CBLCollection *collection, CBLError *_cbl_nullable outError)
Indicates whether the document with the given ID in the given collection has local changes that have ...
_cbl_warn_unused CBLListenerToken * CBLReplicator_AddChangeListener(CBLReplicator *, CBLReplicatorChangeListener, void *_cbl_nullable context)
Registers a listener that will be called when the replicator's status changes.
void CBLAuth_Free(CBLAuthenticator *_cbl_nullable)
Frees a CBLAuthenticator object.
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 of the default collection pushed by...
Definition: CBLReplicator.h:175
CBLDocumentFlags
Flags describing a replicated document.
Definition: CBLReplicator.h:86
FLSliceResult(* CBLDocumentPropertyDecryptor)(void *context, FLString scope, FLString collection, 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.
Definition: CBLReplicator.h:278
CBLReplicatorType
Direction of replication: push, pull, or both.
Definition: CBLReplicator.h:78
void CBLReplicator_SetSuspended(CBLReplicator *repl, bool suspended)
Puts the replicator in or out of "suspended" state.
void CBLReplicator_SetHostReachable(CBLReplicator *, bool reachable)
Informs the replicator whether it's considered possible to reach the remote host with the current net...
_cbl_warn_unused CBLEndpoint * CBLEndpoint_CreateWithLocalDB(CBLDatabase *)
Creates a new endpoint representing another local database.
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.
Definition: CBLReplicator.h:126
_cbl_warn_unused CBLListenerToken * CBLReplicator_AddDocumentReplicationListener(CBLReplicator *, CBLDocumentReplicationListener, void *_cbl_nullable context)
Registers a listener that will be called when documents are replicated.
_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.
const CBLReplicatorConfiguration * CBLReplicator_Config(CBLReplicator *)
Returns the configuration of an existing replicator.
@ kCBLProxyHTTP
HTTP proxy; must support 'CONNECT' method.
Definition: CBLReplicator.h:137
@ kCBLProxyHTTPS
HTTPS proxy; must support 'CONNECT' method.
Definition: CBLReplicator.h:138
@ kCBLReplicatorConnecting
The replicator is connecting to the remote host.
Definition: CBLReplicator.h:506
@ kCBLReplicatorOffline
The replicator is offline, as the remote host is unreachable.
Definition: CBLReplicator.h:505
@ kCBLReplicatorStopped
The replicator is unstarted, finished, or hit a fatal error.
Definition: CBLReplicator.h:504
@ kCBLReplicatorIdle
The replicator is inactive, waiting for changes to sync.
Definition: CBLReplicator.h:507
@ kCBLReplicatorBusy
The replicator is actively transferring data.
Definition: CBLReplicator.h:508
@ kCBLDocumentFlagsAccessRemoved
Lost access to the document on the server.
Definition: CBLReplicator.h:88
@ kCBLDocumentFlagsDeleted
The document has been deleted.
Definition: CBLReplicator.h:87
@ kCBLReplicatorTypePushAndPull
Bidirectional; both push and pull.
Definition: CBLReplicator.h:79
@ kCBLReplicatorTypePush
Pushing changes to the target.
Definition: CBLReplicator.h:80
@ kCBLReplicatorTypePull
Pulling changes from the target.
Definition: CBLReplicator.h:81
const struct _FLDict * FLDict
A reference to a dictionary (map) value.
Definition: FLBase.h:37
const struct _FLArray * FLArray
A reference to an array value.
Definition: FLBase.h:36
A struct holding information about an error.
Definition: CBLBase.h:104
Proxy settings for the replicator.
Definition: CBLReplicator.h:143
uint16_t port
Proxy server port.
Definition: CBLReplicator.h:146
FLString hostname
Proxy server hostname or IP address.
Definition: CBLReplicator.h:145
FLString password
Password for proxy auth.
Definition: CBLReplicator.h:148
FLString username
Username for proxy auth (optional)
Definition: CBLReplicator.h:147
CBLProxyType type
Type of proxy.
Definition: CBLReplicator.h:144
Information about a document that's been pushed or pulled.
Definition: CBLReplicator.h:608
CBLError error
If the code is nonzero, the document failed to replicate.
Definition: CBLReplicator.h:611
FLString collection
The collection name.
Definition: CBLReplicator.h:613
CBLDocumentFlags flags
Indicates whether the document was deleted or removed.
Definition: CBLReplicator.h:610
FLString ID
The document ID.
Definition: CBLReplicator.h:609
FLString scope
The scope name of the collection.
Definition: CBLReplicator.h:612
The collection and the configuration that can be configured specifically for the replication.
Definition: CBLReplicator.h:294
CBLReplicationFilter _cbl_nullable pullFilter
Optional callback to validate incoming docs.
Definition: CBLReplicator.h:300
FLArray _cbl_nullable channels
Optional set of channels to pull from.
Definition: CBLReplicator.h:304
CBLReplicationFilter _cbl_nullable pushFilter
Optional callback to filter which docs are pushed.
Definition: CBLReplicator.h:299
CBLConflictResolver _cbl_nullable conflictResolver
Optional conflict-resolver callback.
Definition: CBLReplicator.h:297
FLArray _cbl_nullable documentIDs
Optional set of document IDs to replicate.
Definition: CBLReplicator.h:305
CBLCollection * collection
The collection.
Definition: CBLReplicator.h:295
The configuration of a replicator.
Definition: CBLReplicator.h:309
void *_cbl_nullable context
Arbitrary value that will be passed to callbacks.
Definition: CBLReplicator.h:407
unsigned maxAttemptWaitTime
Max wait time between retry attempts in seconds.
Definition: CBLReplicator.h:347
const CBLProxySettings *_cbl_nullable proxy
HTTP client proxy settings.
Definition: CBLReplicator.h:366
FLArray _cbl_nullable channels
Optional set of channels to pull from when replicating with the default collection.
Definition: CBLReplicator.h:382
bool disableAutoPurge
If auto purge is active, then the library will automatically purge any documents that the replicating...
Definition: CBLReplicator.h:335
bool continuous
Continuous replication?.
Definition: CBLReplicator.h:323
CBLReplicatorType replicatorType
Push, pull or both.
Definition: CBLReplicator.h:320
CBLReplicationCollection *_cbl_nullable collections
The collections to replicate with the target's endpoint (Required if the database is not set).
Definition: CBLReplicator.h:429
FLSlice pinnedServerCertificate
An X.509 cert (PEM or DER) to "pin" for TLS connections.
Definition: CBLReplicator.h:373
unsigned heartbeat
The heartbeat interval in seconds.
Definition: CBLReplicator.h:353
FLArray _cbl_nullable documentIDs
Optional set of document IDs to replicate when replicating with the default collection.
Definition: CBLReplicator.h:387
unsigned maxAttempts
Max retry attempts where the initial connect to replicate counts toward the given value.
Definition: CBLReplicator.h:343
bool acceptParentDomainCookies
The option to remove the restriction that does not allow the replicator to save the parent-domain coo...
Definition: CBLReplicator.h:444
FLDict _cbl_nullable headers
Extra HTTP headers to add to the WebSocket request.
Definition: CBLReplicator.h:367
size_t collectionCount
The number of collections (Required if the database is not set.
Definition: CBLReplicator.h:432
CBLPropertyDecryptor _cbl_nullable propertyDecryptor
Optional callback to decrypt encrypted CBLEncryptable values of the documents in the default collecti...
Definition: CBLReplicator.h:419
CBLPropertyEncryptor _cbl_nullable propertyEncryptor
Optional callback to encrypt CBLEncryptable values of the documents in the default collection.
Definition: CBLReplicator.h:414
CBLAuthenticator *_cbl_nullable authenticator
Authentication credentials, if needed.
Definition: CBLReplicator.h:365
CBLEndpoint * endpoint
The address of the other database to replicate with (Required)
Definition: CBLReplicator.h:315
CBLConflictResolver _cbl_nullable conflictResolver
Optional conflict-resolver callback.
Definition: CBLReplicator.h:404
CBLDocumentPropertyEncryptor _cbl_nullable documentPropertyEncryptor
Optional callback to encrypt CBLEncryptable values.
Definition: CBLReplicator.h:422
CBLDocumentPropertyDecryptor _cbl_nullable documentPropertyDecryptor
Optional callback to decrypt encrypted CBLEncryptable values.
Definition: CBLReplicator.h:425
CBLReplicationFilter _cbl_nullable pushFilter
Optional callback to filter which docs are pushed when replicating with the default collection.
Definition: CBLReplicator.h:392
FLSlice trustedRootCertificates
Set of anchor certs (PEM format)
Definition: CBLReplicator.h:374
CBLReplicationFilter _cbl_nullable pullFilter
Optional callback to validate incoming docs when replicating with the default collection.
Definition: CBLReplicator.h:397
CBLDatabase *_cbl_nullable database
The database to replicate.
Definition: CBLReplicator.h:313
A fractional progress value, ranging from 0.0 to 1.0 as replication progresses.
Definition: CBLReplicator.h:515
uint64_t documentCount
Number of documents transferred so far.
Definition: CBLReplicator.h:517
float complete
Very-approximate fractional completion, from 0.0 to 1.0.
Definition: CBLReplicator.h:516
A replicator's current status.
Definition: CBLReplicator.h:521
CBLError error
Error, if any.
Definition: CBLReplicator.h:524
CBLReplicatorActivityLevel activity
Current state.
Definition: CBLReplicator.h:522
CBLReplicatorProgress progress
Approximate fraction complete.
Definition: CBLReplicator.h:523
A simple reference to a block of memory.
Definition: FLSlice.h:45
A heap-allocated block of memory returned from an API call.
Definition: FLSlice.h:63