CBLReplicator.h

Go to the documentation of this file.

//
// CBLReplicator.h
//
// Copyright (c) 2018 Couchbase, Inc All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
 
#pragma once
#include "CBLBase.h"
#include "CBLTLSIdentity.h"
 
CBL_CAPI_BEGIN
 
CBL_PUBLIC extern const FLString kCBLAuthDefaultCookieName;
 
typedef struct CBLEndpoint CBLEndpoint;
 
_cbl_warn_unused
CBLEndpoint* _cbl_nullable CBLEndpoint_CreateWithURL(FLString url,
                                                     CBLError* _cbl_nullable outError) CBLAPI;
 
#ifdef COUCHBASE_ENTERPRISE
_cbl_warn_unused
CBLEndpoint* CBLEndpoint_CreateWithLocalDB(CBLDatabase*) CBLAPI;
#endif
 
void CBLEndpoint_Free(CBLEndpoint* _cbl_nullable) CBLAPI;
 
 
typedef struct CBLAuthenticator CBLAuthenticator;
 
_cbl_warn_unused
CBLAuthenticator* CBLAuth_CreatePassword(FLString username, FLString password) CBLAPI;
 
_cbl_warn_unused
CBLAuthenticator* CBLAuth_CreateSession(FLString sessionID, FLString cookieName) CBLAPI;
 
#ifdef COUCHBASE_ENTERPRISE
 
_cbl_warn_unused
CBLAuthenticator* CBLAuth_CreateCertificate(CBLTLSIdentity* identity) CBLAPI;
 
#endif
 
void CBLAuth_Free(CBLAuthenticator* _cbl_nullable) CBLAPI;
 
 
typedef CBL_ENUM(uint8_t, CBLReplicatorType) {
    kCBLReplicatorTypePushAndPull = 0,    
    kCBLReplicatorTypePush,               
    kCBLReplicatorTypePull                
};
 
 
typedef CBL_OPTIONS(unsigned, CBLDocumentFlags) {
    kCBLDocumentFlagsDeleted        = 1 << 0,   
    kCBLDocumentFlagsAccessRemoved  = 1 << 1    
};
 
 
typedef bool (*CBLReplicationFilter)(void* _cbl_nullable context,
                                     CBLDocument* document,
                                     CBLDocumentFlags flags);
 
typedef const CBLDocument* _cbl_nullable (*CBLConflictResolver)(void* _cbl_nullable context,
                                                  FLString documentID,
                                                  const CBLDocument* _cbl_nullable localDocument,
                                                  const CBLDocument* _cbl_nullable remoteDocument);
 
CBL_PUBLIC extern const CBLConflictResolver CBLDefaultConflictResolver;
 
 
typedef CBL_ENUM(uint8_t, CBLProxyType) {
    kCBLProxyHTTP,                      
    kCBLProxyHTTPS,                     
};
 
 
typedef struct {
    CBLProxyType type;                  
    FLString hostname;               
    uint16_t port;                      
    FLString username;               
    FLString password;               
} CBLProxySettings;
 
#ifdef COUCHBASE_ENTERPRISE
 
typedef FLSliceResult (*CBLPropertyEncryptor) (
    void* context,              
    FLString documentID,        
    FLDict properties,          
    FLString keyPath,           
    FLSlice input,              
    FLStringResult* algorithm,  
    FLStringResult* kid,        
    CBLError* error             
);
 
typedef FLSliceResult (*CBLPropertyDecryptor) (
    void* context,              
    FLString documentID,        
    FLDict properties,          
    FLString keyPath,           
    FLSlice input,              
    FLString algorithm,         
    FLString kid,               
    CBLError* error             
);
 
typedef FLSliceResult (*CBLDocumentPropertyEncryptor) (
    void* context,              
    FLString scope,             
    FLString collection,        
    FLString documentID,        
    FLDict properties,          
    FLString keyPath,           
    FLSlice input,              
    FLStringResult* algorithm,  
    FLStringResult* kid,        
    CBLError* error             
);
 
typedef FLSliceResult (*CBLDocumentPropertyDecryptor) (
    void* context,              
    FLString scope,             
    FLString collection,        
    FLString documentID,        
    FLDict properties,          
    FLString keyPath,           
    FLSlice input,              
    FLString algorithm,         
    FLString kid,               
    CBLError* error             
);
 
#endif
 
typedef struct {
    CBLCollection* collection;                          
    
    CBLConflictResolver _cbl_nullable conflictResolver; 
    
    CBLReplicationFilter _cbl_nullable pushFilter;      
    CBLReplicationFilter _cbl_nullable pullFilter;      
    
    FLArray _cbl_nullable channels;
    FLArray _cbl_nullable documentIDs;                  
} CBLReplicationCollection;
 
typedef struct {
    CBLDatabase* _cbl_nullable database;
    CBLEndpoint* endpoint;                              
    
    //-- Types:
    
    CBLReplicatorType replicatorType;
    
    bool continuous;
    
    //-- Auto Purge:
    
    bool disableAutoPurge;
    
    //-- Retry Logic:
    
    unsigned maxAttempts;
    
    unsigned maxAttemptWaitTime;
    
    //-- WebSocket:
    
    unsigned heartbeat;
    
#ifdef __CBL_REPLICATOR_NETWORK_INTERFACE__
    FLString networkInterface;
#endif
    
    //-- HTTP settings:
    
    CBLAuthenticator* _cbl_nullable authenticator;  
    const CBLProxySettings* _cbl_nullable proxy;    
    FLDict _cbl_nullable headers;                   
    
    //-- TLS settings:
    
    FLSlice pinnedServerCertificate;
    FLSlice trustedRootCertificates;                
    
    //-- Filtering:
    
    FLArray _cbl_nullable channels;
    
    FLArray _cbl_nullable documentIDs;
    
    CBLReplicationFilter _cbl_nullable pushFilter;
    
    CBLReplicationFilter _cbl_nullable pullFilter;
    
    //-- Conflict Resolver:
    
    CBLConflictResolver _cbl_nullable conflictResolver;
    
    //-- Context:
    void* _cbl_nullable context;                    
    
#ifdef COUCHBASE_ENTERPRISE
    //-- Property Encryption
    CBLPropertyEncryptor _cbl_nullable propertyEncryptor;
    
    CBLPropertyDecryptor _cbl_nullable propertyDecryptor;
    
    CBLDocumentPropertyEncryptor _cbl_nullable documentPropertyEncryptor;
    
    CBLDocumentPropertyDecryptor _cbl_nullable documentPropertyDecryptor;
#endif
    
    CBLReplicationCollection* _cbl_nullable collections;
    
    size_t collectionCount;
    
    //-- Advanced HTTP settings:
    
    bool acceptParentDomainCookies;
 
#ifdef COUCHBASE_ENTERPRISE
    bool acceptOnlySelfSignedServerCertificate;
#endif
} CBLReplicatorConfiguration;
 
 
CBL_REFCOUNTED(CBLReplicator*, Replicator);
 
_cbl_warn_unused
CBLReplicator* _cbl_nullable CBLReplicator_Create(const CBLReplicatorConfiguration*,
                                                  CBLError* _cbl_nullable outError) CBLAPI;
 
const CBLReplicatorConfiguration* CBLReplicator_Config(CBLReplicator*) CBLAPI;
 
void CBLReplicator_Start(CBLReplicator *replicator,
                         bool resetCheckpoint) CBLAPI;
 
void CBLReplicator_Stop(CBLReplicator*) CBLAPI;
 
void CBLReplicator_SetHostReachable(CBLReplicator*,
                                    bool reachable) CBLAPI;
 
void CBLReplicator_SetSuspended(CBLReplicator* repl, bool suspended) CBLAPI;
 
typedef CBL_ENUM(uint8_t, CBLReplicatorActivityLevel) {
    kCBLReplicatorStopped,    
    kCBLReplicatorOffline,    
    kCBLReplicatorConnecting, 
    kCBLReplicatorIdle,       
    kCBLReplicatorBusy        
};
 
typedef struct {
    float complete;             
    uint64_t documentCount;     
} CBLReplicatorProgress;
 
typedef struct {
    CBLReplicatorActivityLevel activity;    
    CBLReplicatorProgress progress;         
    CBLError error;                         
} CBLReplicatorStatus;
 
CBLReplicatorStatus CBLReplicator_Status(CBLReplicator*) CBLAPI;
 
_cbl_warn_unused
FLDict _cbl_nullable CBLReplicator_PendingDocumentIDs(CBLReplicator*, CBLError* _cbl_nullable outError) CBLAPI;
 
bool CBLReplicator_IsDocumentPending(CBLReplicator *repl,
                                     FLString docID,
                                     CBLError* _cbl_nullable outError) CBLAPI;
 
FLDict _cbl_nullable CBLReplicator_PendingDocumentIDs2(CBLReplicator*,
                                                       const CBLCollection* collection,
                                                       CBLError* _cbl_nullable outError) CBLAPI;
 
bool CBLReplicator_IsDocumentPending2(CBLReplicator *repl,
                                      FLString docID,
                                      const CBLCollection* collection,
                                      CBLError* _cbl_nullable outError) CBLAPI;
 
typedef void (*CBLReplicatorChangeListener)(void* _cbl_nullable context,
                                            CBLReplicator *replicator,
                                            const CBLReplicatorStatus *status);
 
_cbl_warn_unused
CBLListenerToken* CBLReplicator_AddChangeListener(CBLReplicator*,
                                                  CBLReplicatorChangeListener,
                                                  void* _cbl_nullable context) CBLAPI;
 
 
typedef struct {
    FLString ID;                
    CBLDocumentFlags flags;     
    CBLError error;             
    FLString scope;             
    FLString collection;        
} CBLReplicatedDocument;
 
typedef void (*CBLDocumentReplicationListener)(void *context,
                                               CBLReplicator *replicator,
                                               bool isPush,
                                               unsigned numDocuments,
                                               const CBLReplicatedDocument* documents);
 
_cbl_warn_unused
CBLListenerToken* CBLReplicator_AddDocumentReplicationListener(CBLReplicator*,
                                                               CBLDocumentReplicationListener,
                                                               void* _cbl_nullable context) CBLAPI;
 
#ifdef COUCHBASE_ENTERPRISE
 
_cbl_warn_unused
CBLCert* _cbl_nullable CBLReplicator_ServerCertificate(CBLReplicator*) CBLAPI;
 
 
#endif
 
CBL_CAPI_END