The C API of Couchbase Lite, an embedded NoSQL document database for mobile, desktop, and edge devices.
Getting Started
Include cbl/CouchbaseLite.h (or the individual cbl/CBL*.h headers). The API is organized into the groups listed on the Modules page.
if (!db) {
}
}
#define FLSTR(STR)
Macro version of FLStr, for use in initializing compile-time constants.
Definition FLSlice.h:142
void FLMutableDict_SetString(FLMutableDict, FLString key, FLString)
Stores a UTF-8-encoded string into a mutable dictionary.
Definition FLMutable.h:498
CBLCollection *_cbl_nullable CBLDatabase_DefaultCollection(const CBLDatabase *db, CBLError *_cbl_nullable outError)
Returns the default collection.
CBLINLINE void CBLCollection_Release(const CBLCollection *_cbl_nullable t)
Definition CBLCollection.h:66
bool CBLCollection_SaveDocument(CBLCollection *collection, CBLDocument *doc, CBLError *_cbl_nullable outError)
Saves a (mutable) document to the collection.
struct CBLCollection CBLCollection
A collection, a document container.
Definition CBLBase.h:196
struct CBLDatabase CBLDatabase
A connection to an open database.
Definition CBLBase.h:184
bool CBLDatabase_Close(CBLDatabase *, CBLError *_cbl_nullable outError)
Closes an open database.
_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.
CBLINLINE void CBLDatabase_Release(const CBLDatabase *_cbl_nullable t)
Definition CBLDatabase.h:186
CBLINLINE void CBLDocument_Release(const CBLDocument *_cbl_nullable t)
Definition CBLDocument.h:76
struct CBLDocument CBLDocument
An in-memory copy of a document.
Definition CBLBase.h:205
FLMutableDict CBLDocument_MutableProperties(CBLDocument *)
Returns a mutable document's properties as a mutable dictionary.
_cbl_warn_unused CBLDocument * CBLDocument_CreateWithID(FLString docID)
Creates a new, empty document in memory, with the given ID.
struct _FLDict * FLMutableDict
A reference to a mutable dictionary.
Definition FLBase.h:40
A struct holding information about an error.
Definition CBLBase.h:105
Reference Counting
Couchbase Lite objects are reference-counted. Functions that create an object (typically named ..._Create() or ..._New()) return it with a ref-count of 1; release it with the type-safe CBLXxx_Release() function when you are done with it, or it will be leaked. Functions that return an existing object do not change its ref-count: do not release it unless you retained it, and retain it if you need to keep it alive. Each function's documentation states whether you are responsible for releasing the returned object. See Reference Counting for details.
Error Handling
Functions that can fail take a CBLError* out-parameter and signal failure through their return value, typically by returning false or NULL. On failure, the error's domain and code are written to the out-parameter, and CBLError_Message returns a human-readable message for it. See Errors.
Document Data
Document properties are stored as Fleece values: CBLDocument_Properties returns an FLDict, and CBLDocument_MutableProperties returns an FLMutableDict. Strings and binary data are passed as FLString/FLSlice, non-owning views of a byte range that must not outlive the data they point to; use FLSTR() to make one from a string literal. Functions returning FLSliceResult/FLStringResult transfer ownership of heap-allocated data: release the result when done. The Fleece API is documented in this reference under the Fleece topic groups.
1.14.0