Couchbase Lite C
Couchbase Lite C API
Data Structures
CBLDatabase.h File Reference
#include "CBLBase.h"

Go to the source code of this file.

Data Structures

struct  CBLEncryptionKey
 Encryption key specified in a CBLDatabaseConfiguration. More...
 
struct  CBLDatabaseConfiguration
 Database configuration options. More...
 

Functions

Database file operations

These functions operate on database files without opening them.

bool CBL_DatabaseExists (FLString name, FLString inDirectory)
 Returns true if a database with the given name exists in the given directory. More...
 
bool CBL_CopyDatabase (FLString fromPath, FLString toName, const CBLDatabaseConfiguration *_cbl_nullable config, CBLError *_cbl_nullable outError)
 Copies a database file to a new location, and assigns it a new internal UUID to distinguish it from the original database when replicating. More...
 
bool CBL_DeleteDatabase (FLString name, FLString inDirectory, CBLError *_cbl_nullable outError)
 Deletes a database file. More...
 
Database accessors

Getting information about a database.

FLString CBLDatabase_Name (const CBLDatabase *)
 Returns the database's name. More...
 
_cbl_warn_unused FLStringResult CBLDatabase_Path (const CBLDatabase *)
 Returns the database's full filesystem path, or null slice if the database is closed or deleted. More...
 
uint64_t CBLDatabase_Count (const CBLDatabase *)
 Returns the number of documents in the database, or zero if the database is closed or deleted. More...
 
const CBLDatabaseConfiguration CBLDatabase_Config (const CBLDatabase *)
 Returns the database's configuration, as given when it was opened. More...
 

Database configuration

enum  CBLEncryptionAlgorithm : uint32_t { kCBLEncryptionNone = 0 , kCBLEncryptionAES256 }
 Database encryption algorithms (available only in the Enterprise Edition). More...
 
enum  CBLEncryptionKeySize : uint64_t { kCBLEncryptionKeySizeAES256 = 32 }
 Encryption key sizes (in bytes). More...
 
CBLDatabaseConfiguration CBLDatabaseConfiguration_Default (void)
 Returns the default database configuration. More...
 
bool CBLEncryptionKey_FromPassword (CBLEncryptionKey *key, FLString password)
 Derives an encryption key from a password. More...
 
bool CBLEncryptionKey_FromPasswordOld (CBLEncryptionKey *key, FLString password)
 VOLATILE API: Derives an encryption key from a password in a way that is compatible with certain variants of Couchbase Lite in which a slightly different hashing algorithm is used. More...
 

Database lifecycle

Opening, closing, and managing open databases.

enum  CBLMaintenanceType : uint32_t {
  kCBLMaintenanceTypeCompact = 0 , kCBLMaintenanceTypeReindex , kCBLMaintenanceTypeIntegrityCheck , kCBLMaintenanceTypeOptimize ,
  kCBLMaintenanceTypeFullOptimize
}
 Maintenance Type used when performing database maintenance. More...
 
_cbl_warn_unused CBLDatabase *_cbl_nullable CBLDatabase_Open (FLSlice name, const CBLDatabaseConfiguration *_cbl_nullable config, CBLError *_cbl_nullable outError)
 Opens a database, or creates it if it doesn't exist yet, returning a new CBLDatabase instance. More...
 
bool CBLDatabase_Close (CBLDatabase *, CBLError *_cbl_nullable outError)
 Closes an open database. More...
 
static const CBLDatabaseCBLDatabase_Retain (const CBLDatabase *t)
 
static void CBLDatabase_Release (const CBLDatabase *t)
 
bool CBLDatabase_Delete (CBLDatabase *, CBLError *_cbl_nullable outError)
 Closes and deletes a database. More...
 
bool CBLDatabase_BeginTransaction (CBLDatabase *, CBLError *_cbl_nullable outError)
 Begins a transaction. More...
 
bool CBLDatabase_EndTransaction (CBLDatabase *, bool commit, CBLError *_cbl_nullable outError)
 Ends a transaction, either committing or aborting. More...
 
bool CBLDatabase_ChangeEncryptionKey (CBLDatabase *, const CBLEncryptionKey *_cbl_nullable newKey, CBLError *outError)
 Encrypts or decrypts a database, or changes its encryption key. More...
 
bool CBLDatabase_PerformMaintenance (CBLDatabase *db, CBLMaintenanceType type, CBLError *_cbl_nullable outError)
 Performs database maintenance. More...
 

Database listeners

A database change listener lets you detect changes made to all documents in the default collection.

(If you only want to observe specific documents, use a CBLDocumentChangeListener instead.)

Note
If there are multiple CBLDatabase instances on the same database file, each one's listeners will be notified of changes made by other database instances.
Warning
Changes made to the database file by other processes will not be notified.
typedef void(* CBLDatabaseChangeListener) (void *_cbl_nullable context, const CBLDatabase *db, unsigned numDocs, FLString docIDs[])
 A default collection change listener callback, invoked after one or more documents in the default collection are changed on disk. More...
 
_cbl_warn_unused CBLListenerTokenCBLDatabase_AddChangeListener (const CBLDatabase *db, CBLDatabaseChangeListener listener, void *_cbl_nullable context)
 Registers a default collection change listener callback. More...
 

Scheduling notifications

Applications may want control over when Couchbase Lite notifications (listener callbacks) happen.

They may want them called on a specific thread, or at certain times during an event loop. This behavior may vary by database, if for instance each database is associated with a separate thread.

The API calls here enable this. When notifications are "buffered" for a database, calls to listeners will be deferred until the application explicitly allows them. Instead, a single callback will be issued when the first notification becomes available; this gives the app a chance to schedule a time when the notifications should be sent and callbacks called.

typedef void(* CBLNotificationsReadyCallback) (void *_cbl_nullable context, CBLDatabase *db)
 Callback indicating that the database (or an object belonging to it) is ready to call one or more listeners. More...
 
void CBLDatabase_BufferNotifications (CBLDatabase *db, CBLNotificationsReadyCallback _cbl_nullable callback, void *_cbl_nullable context)
 Switches the database to buffered-notification mode. More...
 
void CBLDatabase_SendNotifications (CBLDatabase *db)
 Immediately issues all pending notifications for this database, by calling their listener callbacks. More...