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#include "fleece/Fleece.h"
22
24
35
37typedef struct CBLEndpoint CBLEndpoint;
38
50 CBLError* _cbl_nullable outError) CBLAPI;
51
52#ifdef COUCHBASE_ENTERPRISE
56#endif
57
60
61
64
68
73
76
77
79typedef CBL_ENUM(uint8_t, CBLReplicatorType) {
83};
84
85
87typedef CBL_OPTIONS(unsigned, CBLDocumentFlags) {
90};
91
92
101typedef bool (*CBLReplicationFilter)(void* _cbl_nullable context,
102 CBLDocument* document,
103 CBLDocumentFlags flags);
104
128 FLString documentID,
129 const CBLDocument* _cbl_nullable localDocument,
130 const CBLDocument* _cbl_nullable remoteDocument);
131
134
135
137typedef CBL_ENUM(uint8_t, CBLProxyType) {
140};
141
142
144typedef struct {
147 uint16_t port;
151
152#ifdef COUCHBASE_ENTERPRISE
153
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
210 void* context,
211 FLString documentID,
212 FLDict properties,
213 FLString keyPath,
214 FLSlice input,
215 FLString algorithm,
216 FLString kid,
217 CBLError* error
218);
219
220#endif
221
223typedef struct {
228 //-- Auto Purge:
239 //-- Retry Logic:
240 unsigned maxAttempts;
243 //-- WebSocket:
244 unsigned heartbeat;
245 //-- HTTP settings:
249 //-- TLS settings:
252 //-- Filtering:
259
260#ifdef COUCHBASE_ENTERPRISE
261 //-- Property Encryption
264#endif
265
266 //-- Advanced HTTP settings:
267
278
286
290 CBLError* _cbl_nullable outError) CBLAPI;
291
294
303 bool resetCheckpoint) CBLAPI;
304
309
316 bool reachable) CBLAPI;
317
324
341
346typedef struct {
347 float complete;
348 uint64_t documentCount;
350
352typedef struct {
357
360
376 CBLError* _cbl_nullable outError) CBLAPI;
377
387 FLString docID,
388 CBLError* _cbl_nullable outError) CBLAPI;
389
390
398typedef void (*CBLReplicatorChangeListener)(void* _cbl_nullable context,
399 CBLReplicator *replicator,
400 const CBLReplicatorStatus *status);
401
406 void* _cbl_nullable context) CBLAPI;
407
408
410typedef struct {
415
425typedef void (*CBLDocumentReplicationListener)(void *context,
426 CBLReplicator *replicator,
427 bool isPush,
428 unsigned numDocuments,
429 const CBLReplicatedDocument* documents);
430
435 void* _cbl_nullable context) CBLAPI;
436
#define CBL_OPTIONS(_type, _name)
Definition: CBL_Compat.h:57
#define CBLAPI
Definition: CBL_Compat.h:98
#define _cbl_nullable
Definition: CBL_Compat.h:86
#define CBL_CAPI_BEGIN
Definition: CBL_Compat.h:99
#define CBL_CAPI_END
Definition: CBL_Compat.h:100
#define CBL_PUBLIC
Definition: CBL_Compat.h:117
#define CBL_ENUM(_type, _name)
Definition: CBL_Compat.h:56
#define _cbl_warn_unused
Definition: CBL_Compat.h:41
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:191
struct CBLListenerToken CBLListenerToken
An opaque 'cookie' representing a registered listener callback.
Definition: CBLBase.h:259
#define CBL_REFCOUNTED(TYPE, NAME)
Definition: CBLBase.h:170
CBLProxyType
Types of proxy servers, for CBLProxySettings.
Definition: CBLReplicator.h:137
struct CBLAuthenticator CBLAuthenticator
An opaque object representing authentication credentials for a remote server.
Definition: CBLReplicator.h:63
_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:37
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:101
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 pulled by the replicator.
Definition: CBLReplicator.h:209
_cbl_warn_unused CBLAuthenticator * CBLAuth_CreatePassword(FLString username, FLString password)
Creates an authenticator for HTTP Basic (username/password) auth.
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 t...
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:212
_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 have local changes that have not yet been pushed to the server by this repl...
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:398
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:425
CBL_PUBLIC const CBLConflictResolver CBLDefaultConflictResolver
Default conflict resolver.
CBLReplicatorActivityLevel
The possible states a replicator can be in during its lifecycle.
Definition: CBLReplicator.h:334
_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.
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 pushed by the replicator.
Definition: CBLReplicator.h:175
CBLDocumentFlags
Flags describing a replicated document.
Definition: CBLReplicator.h:87
CBLReplicatorType
Direction of replication: push, pull, or both.
Definition: CBLReplicator.h:79
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:127
_cbl_warn_unused CBLListenerToken * CBLReplicator_AddDocumentReplicationListener(CBLReplicator *, CBLDocumentReplicationListener, void *_cbl_nullable context)
Adds 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:138
@ kCBLProxyHTTPS
HTTPS proxy; must support 'CONNECT' method.
Definition: CBLReplicator.h:139
@ kCBLReplicatorConnecting
The replicator is connecting to the remote host.
Definition: CBLReplicator.h:337
@ kCBLReplicatorOffline
The replicator is offline, as the remote host is unreachable.
Definition: CBLReplicator.h:336
@ kCBLReplicatorStopped
The replicator is unstarted, finished, or hit a fatal error.
Definition: CBLReplicator.h:335
@ kCBLReplicatorIdle
The replicator is inactive, waiting for changes to sync.
Definition: CBLReplicator.h:338
@ kCBLReplicatorBusy
The replicator is actively transferring data.
Definition: CBLReplicator.h:339
@ kCBLDocumentFlagsAccessRemoved
Lost access to the document on the server.
Definition: CBLReplicator.h:89
@ kCBLDocumentFlagsDeleted
The document has been deleted.
Definition: CBLReplicator.h:88
@ kCBLReplicatorTypePushAndPull
Bidirectional; both push and pull.
Definition: CBLReplicator.h:80
@ kCBLReplicatorTypePush
Pushing changes to the target.
Definition: CBLReplicator.h:81
@ kCBLReplicatorTypePull
Pulling changes from the target.
Definition: CBLReplicator.h:82
const struct _FLDict * FLDict
A reference to a dictionary (map) value.
Definition: Fleece.h:51
const struct _FLArray * FLArray
A reference to an array value.
Definition: Fleece.h:50
A struct holding information about an error.
Definition: CBLBase.h:104
Proxy settings for the replicator.
Definition: CBLReplicator.h:144
uint16_t port
Proxy server port.
Definition: CBLReplicator.h:147
FLString hostname
Proxy server hostname or IP address.
Definition: CBLReplicator.h:146
FLString password
Password for proxy auth.
Definition: CBLReplicator.h:149
FLString username
Username for proxy auth (optional)
Definition: CBLReplicator.h:148
CBLProxyType type
Type of proxy.
Definition: CBLReplicator.h:145
Information about a document that's been pushed or pulled.
Definition: CBLReplicator.h:410
CBLError error
If the code is nonzero, the document failed to replicate.
Definition: CBLReplicator.h:413
CBLDocumentFlags flags
Indicates whether the document was deleted or removed.
Definition: CBLReplicator.h:412
FLString ID
The document ID.
Definition: CBLReplicator.h:411
The configuration of a replicator.
Definition: CBLReplicator.h:223
void *_cbl_nullable context
Arbitrary value that will be passed to callbacks.
Definition: CBLReplicator.h:258
unsigned maxAttemptWaitTime
Max wait time between retry attempts in seconds. Specify 0 to use the default value of 300 seconds.
Definition: CBLReplicator.h:242
const CBLProxySettings *_cbl_nullable proxy
HTTP client proxy settings.
Definition: CBLReplicator.h:247
FLArray _cbl_nullable channels
Optional set of channels to pull from.
Definition: CBLReplicator.h:253
bool disableAutoPurge
If auto purge is active, then the library will automatically purge any documents that the replicating...
Definition: CBLReplicator.h:238
bool continuous
Continuous replication?
Definition: CBLReplicator.h:227
CBLReplicatorType replicatorType
Push, pull or both.
Definition: CBLReplicator.h:226
FLSlice pinnedServerCertificate
An X.509 cert to "pin" TLS connections to (PEM or DER)
Definition: CBLReplicator.h:250
unsigned heartbeat
The heartbeat interval in seconds. Specify 0 to use the default value of 300 seconds.
Definition: CBLReplicator.h:244
FLArray _cbl_nullable documentIDs
Optional set of document IDs to replicate.
Definition: CBLReplicator.h:254
unsigned maxAttempts
Max retry attempts where the initial connect to replicate counts toward the given value.
Definition: CBLReplicator.h:240
bool acceptParentDomainCookies
The option to remove the restriction that does not allow the replicator to save the parent-domain coo...
Definition: CBLReplicator.h:276
FLDict _cbl_nullable headers
Extra HTTP headers to add to the WebSocket request.
Definition: CBLReplicator.h:248
CBLPropertyDecryptor _cbl_nullable propertyDecryptor
Optional callback to decrypt encrypted CBLEncryptable values.
Definition: CBLReplicator.h:263
CBLPropertyEncryptor _cbl_nullable propertyEncryptor
Optional callback to encrypt CBLEncryptable values.
Definition: CBLReplicator.h:262
CBLDatabase * database
The database to replicate.
Definition: CBLReplicator.h:224
CBLAuthenticator *_cbl_nullable authenticator
Authentication credentials, if needed.
Definition: CBLReplicator.h:246
CBLEndpoint * endpoint
The address of the other database to replicate with.
Definition: CBLReplicator.h:225
CBLConflictResolver _cbl_nullable conflictResolver
Optional conflict-resolver callback.
Definition: CBLReplicator.h:257
CBLReplicationFilter _cbl_nullable pushFilter
Optional callback to filter which docs are pushed.
Definition: CBLReplicator.h:255
FLSlice trustedRootCertificates
Set of anchor certs (PEM format)
Definition: CBLReplicator.h:251
CBLReplicationFilter _cbl_nullable pullFilter
Optional callback to validate incoming docs.
Definition: CBLReplicator.h:256
A fractional progress value, ranging from 0.0 to 1.0 as replication progresses.
Definition: CBLReplicator.h:346
uint64_t documentCount
Very-approximate fractional completion, from 0.0 to 1.0.
Definition: CBLReplicator.h:348
float complete
Definition: CBLReplicator.h:347
A replicator's current status.
Definition: CBLReplicator.h:352
CBLError error
Error, if any.
Definition: CBLReplicator.h:355
CBLReplicatorActivityLevel activity
Current state.
Definition: CBLReplicator.h:353
CBLReplicatorProgress progress
Approximate fraction complete.
Definition: CBLReplicator.h:354
A simple reference to a block of memory.
Definition: FLSlice.h:46
A heap-allocated block of memory returned from an API call.
Definition: FLSlice.h:64