Couchbase Lite C
Couchbase Lite C API
Typedefs | Variables
Documents

A CBLDocument is essentially a JSON object with an ID string that's unique in its database. More...

Typedefs

typedef struct CBLDocument CBLDocument
 An in-memory copy of a document. More...
 

Variables

CBL_PUBLIC const FLSlice kCBLTypeProperty
 "@type" More...
 

Document lifecycle

enum  CBLConcurrencyControl : uint8_t { kCBLConcurrencyControlLastWriteWins , kCBLConcurrencyControlFailOnConflict }
 Conflict-handling options when saving or deleting a document. More...
 
typedef bool(* CBLConflictHandler) (void *_cbl_nullable context, CBLDocument *_cbl_nullable documentBeingSaved, const CBLDocument *_cbl_nullable conflictingDocument)
 Custom conflict handler for use when saving or deleting a document. More...
 
_cbl_warn_unused const CBLDocument *_cbl_nullable CBLDatabase_GetDocument (const CBLDatabase *database, FLString docID, CBLError *_cbl_nullable outError)
 Reads a document from the database, creating a new (immutable) CBLDocument object. More...
 
static const CBLDocumentCBLDocument_Retain (const CBLDocument *t)
 
static void CBLDocument_Release (const CBLDocument *t)
 
bool CBLDatabase_SaveDocument (CBLDatabase *db, CBLDocument *doc, CBLError *_cbl_nullable outError)
 Saves a (mutable) document to the database. More...
 
bool CBLDatabase_SaveDocumentWithConcurrencyControl (CBLDatabase *db, CBLDocument *doc, CBLConcurrencyControl concurrency, CBLError *_cbl_nullable outError)
 Saves a (mutable) document to the database. More...
 
bool CBLDatabase_SaveDocumentWithConflictHandler (CBLDatabase *db, CBLDocument *doc, CBLConflictHandler conflictHandler, void *_cbl_nullable context, CBLError *_cbl_nullable outError)
 Saves a (mutable) document to the database, allowing for custom conflict handling in the event that the document has been updated since doc was loaded. More...
 
bool CBLDatabase_DeleteDocument (CBLDatabase *db, const CBLDocument *document, CBLError *_cbl_nullable outError)
 Deletes a document from the database. More...
 
bool CBLDatabase_DeleteDocumentWithConcurrencyControl (CBLDatabase *db, const CBLDocument *document, CBLConcurrencyControl concurrency, CBLError *_cbl_nullable outError)
 Deletes a document from the database. More...
 
bool CBLDatabase_PurgeDocument (CBLDatabase *db, const CBLDocument *document, CBLError *_cbl_nullable outError)
 Purges a document. More...
 
bool CBLDatabase_PurgeDocumentByID (CBLDatabase *database, FLString docID, CBLError *_cbl_nullable outError)
 Purges a document, given only its ID. More...
 

Document listeners

A document change listener lets you detect changes made to a specific document after they are persisted to the database.

Note
If there are multiple CBLDatabase instances on the same database file, each one's document listeners will be notified of changes made by other database instances.
typedef void(* CBLDocumentChangeListener) (void *context, const CBLDatabase *db, FLString docID)
 A document change listener callback, invoked after a specific document is changed on disk. More...
 
_cbl_warn_unused CBLListenerTokenCBLDatabase_AddDocumentChangeListener (const CBLDatabase *db, FLString docID, CBLDocumentChangeListener listener, void *_cbl_nullable context)
 Registers a document change listener callback. More...
 

Mutable documents

The type CBLDocument* without a const qualifier refers to a mutable document instance.

A mutable document exposes its properties as a mutable dictionary, so you can change them in place and then call CBLDatabase_SaveDocument to persist the changes.

_cbl_warn_unused CBLDocument *_cbl_nullable CBLDatabase_GetMutableDocument (CBLDatabase *database, FLString docID, CBLError *_cbl_nullable outError)
 Reads a document from the database, in mutable form that can be updated and saved. More...
 
_cbl_warn_unused CBLDocumentCBLDocument_Create (void)
 Creates a new, empty document in memory, with a randomly-generated unique ID. More...
 
_cbl_warn_unused CBLDocumentCBLDocument_CreateWithID (FLString docID)
 Creates a new, empty document in memory, with the given ID. More...
 
_cbl_warn_unused CBLDocumentCBLDocument_MutableCopy (const CBLDocument *original)
 Creates a new mutable CBLDocument instance that refers to the same document as the original. More...
 

Document properties and metadata

A document's body is essentially a JSON object.

The properties are accessed in memory using the Fleece API, with the body itself being a dictionary).

FLString CBLDocument_ID (const CBLDocument *)
 Returns a document's ID. More...
 
FLString CBLDocument_RevisionID (const CBLDocument *)
 Returns a document's revision ID, which is a short opaque string that's guaranteed to be unique to every change made to the document. More...
 
uint64_t CBLDocument_Sequence (const CBLDocument *)
 Returns a document's current sequence in the local database. More...
 
FLDict CBLDocument_Properties (const CBLDocument *)
 Returns a document's properties as a dictionary. More...
 
FLMutableDict CBLDocument_MutableProperties (CBLDocument *)
 Returns a mutable document's properties as a mutable dictionary. More...
 
void CBLDocument_SetProperties (CBLDocument *, FLMutableDict properties)
 Sets a mutable document's properties. More...
 
_cbl_warn_unused FLSliceResult CBLDocument_CreateJSON (const CBLDocument *)
 Returns a document's properties as JSON. More...
 
bool CBLDocument_SetJSON (CBLDocument *, FLSlice json, CBLError *_cbl_nullable outError)
 Sets a mutable document's properties from a JSON string. More...
 
CBLTimestamp CBLDatabase_GetDocumentExpiration (CBLDatabase *db, FLSlice docID, CBLError *_cbl_nullable outError)
 Returns the time, if any, at which a given document will expire and be purged. More...
 
bool CBLDatabase_SetDocumentExpiration (CBLDatabase *db, FLSlice docID, CBLTimestamp expiration, CBLError *_cbl_nullable outError)
 Sets or clears the expiration time of a document. More...
 

Detailed Description

A CBLDocument is essentially a JSON object with an ID string that's unique in its database.

Typedef Documentation

◆ CBLConflictHandler

typedef bool(* CBLConflictHandler) (void *_cbl_nullable context, CBLDocument *_cbl_nullable documentBeingSaved, const CBLDocument *_cbl_nullable conflictingDocument)

Custom conflict handler for use when saving or deleting a document.

This handler is called if the save would cause a conflict, i.e. if the document in the database has been updated (probably by a pull replicator, or by application code on another thread) since it was loaded into the CBLDocument being saved.

Parameters
contextThe value of the context parameter you passed to CBLDatabase_SaveDocumentWithConflictHandler.
documentBeingSavedThe document being saved (same as the parameter you passed to CBLDatabase_SaveDocumentWithConflictHandler.) The callback may modify this document's properties as necessary to resolve the conflict.
conflictingDocumentThe revision of the document currently in the database, which has been changed since documentBeingSaved was loaded. May be NULL, meaning that the document has been deleted.
Returns
True to save the document, false to abort the save.

◆ CBLDocument

typedef struct CBLDocument CBLDocument

An in-memory copy of a document.

CBLDocument objects can be mutable or immutable. Immutable objects are referenced by const pointers; mutable ones by non-const pointers. This prevents you from accidentally calling a mutable-document function on an immutable document.

◆ CBLDocumentChangeListener

typedef void(* CBLDocumentChangeListener) (void *context, const CBLDatabase *db, FLString docID)

A document change listener callback, invoked after a specific document is changed on disk.

Warning
By default, this listener may be called on arbitrary threads. If your code isn't prepared for that, you may want to use CBLDatabase_BufferNotifications so that listeners will be called in a safe context.
Parameters
contextAn arbitrary value given when the callback was registered.
dbThe database containing the document.
docIDThe document's ID.

Enumeration Type Documentation

◆ CBLConcurrencyControl

enum CBLConcurrencyControl : uint8_t

Conflict-handling options when saving or deleting a document.

Enumerator
kCBLConcurrencyControlLastWriteWins 

The current save/delete will overwrite a conflicting revision if there is a conflict.

kCBLConcurrencyControlFailOnConflict 

The current save/delete will fail if there is a conflict.

Function Documentation

◆ CBLDatabase_AddDocumentChangeListener()

_cbl_warn_unused CBLListenerToken * CBLDatabase_AddDocumentChangeListener ( const CBLDatabase db,
FLString  docID,
CBLDocumentChangeListener  listener,
void *_cbl_nullable  context 
)

Registers a document change listener callback.

It will be called after a specific document is changed on disk.

Parameters
dbThe database to observe.
docIDThe ID of the document to observe.
listenerThe callback to be invoked.
contextAn opaque value that will be passed to the callback.
Returns
A token to be passed to CBLListener_Remove when it's time to remove the listener.

◆ CBLDatabase_DeleteDocument()

bool CBLDatabase_DeleteDocument ( CBLDatabase db,
const CBLDocument document,
CBLError *_cbl_nullable  outError 
)

Deletes a document from the database.

Deletions are replicated.

Warning
You are still responsible for releasing the CBLDocument.
Parameters
dbThe database containing the document.
documentThe document to delete.
outErrorOn failure, the error will be written here.
Returns
True if the document was deleted, false if an error occurred.

◆ CBLDatabase_DeleteDocumentWithConcurrencyControl()

bool CBLDatabase_DeleteDocumentWithConcurrencyControl ( CBLDatabase db,
const CBLDocument document,
CBLConcurrencyControl  concurrency,
CBLError *_cbl_nullable  outError 
)

Deletes a document from the database.

Deletions are replicated.

Warning
You are still responsible for releasing the CBLDocument.
Parameters
dbThe database containing the document.
documentThe document to delete.
concurrencyConflict-handling strategy.
outErrorOn failure, the error will be written here.
Returns
True if the document was deleted, false if an error occurred.

◆ CBLDatabase_GetDocument()

_cbl_warn_unused const CBLDocument *_cbl_nullable CBLDatabase_GetDocument ( const CBLDatabase database,
FLString  docID,
CBLError *_cbl_nullable  outError 
)

Reads a document from the database, creating a new (immutable) CBLDocument object.

Each call to this function creates a new object (which must later be released.)

Note
If you are reading the document in order to make changes to it, call CBLDatabase_GetMutableDocument instead.
Parameters
databaseThe database.
docIDThe ID of the document.
outErrorOn failure, the error will be written here. (A nonexistent document is not considered a failure; in that event the error code will be zero.)
Returns
A new CBLDocument instance, or NULL if the doc doesn't exist or an error occurred.

◆ CBLDatabase_GetDocumentExpiration()

CBLTimestamp CBLDatabase_GetDocumentExpiration ( CBLDatabase db,
FLSlice  docID,
CBLError *_cbl_nullable  outError 
)

Returns the time, if any, at which a given document will expire and be purged.

Documents don't normally expire; you have to call CBLDatabase_SetDocumentExpiration to set a document's expiration time.

Parameters
dbThe database.
docIDThe ID of the document.
outErrorOn failure, an error is written here.
Returns
The expiration time as a CBLTimestamp (milliseconds since Unix epoch), or 0 if the document does not have an expiration, or -1 if the call failed.

◆ CBLDatabase_GetMutableDocument()

_cbl_warn_unused CBLDocument *_cbl_nullable CBLDatabase_GetMutableDocument ( CBLDatabase database,
FLString  docID,
CBLError *_cbl_nullable  outError 
)

Reads a document from the database, in mutable form that can be updated and saved.

(This function is otherwise identical to CBLDatabase_GetDocument.)

Note
You must release the document when you're done with it.
Parameters
databaseThe database.
docIDThe ID of the document.
outErrorOn failure, the error will be written here. (A nonexistent document is not considered a failure; in that event the error code will be zero.)
Returns
A new CBLDocument instance, or NULL if the doc doesn't exist or an error occurred.

◆ CBLDatabase_PurgeDocument()

bool CBLDatabase_PurgeDocument ( CBLDatabase db,
const CBLDocument document,
CBLError *_cbl_nullable  outError 
)

Purges a document.

This removes all traces of the document from the database. Purges are not replicated. If the document is changed on a server, it will be re-created when pulled.

Warning
You are still responsible for releasing the CBLDocument reference.
Note
If you don't have the document in memory already, CBLDatabase_PurgeDocumentByID is a simpler shortcut.
Parameters
dbThe database containing the document.
documentThe document to delete.
outErrorOn failure, the error will be written here.
Returns
True if the document was purged, false if it doesn't exist or the purge failed.

◆ CBLDatabase_PurgeDocumentByID()

bool CBLDatabase_PurgeDocumentByID ( CBLDatabase database,
FLString  docID,
CBLError *_cbl_nullable  outError 
)

Purges a document, given only its ID.

Note
If no document with that ID exists, this function will return false but the error code will be zero.
Parameters
databaseThe database.
docIDThe document ID to purge.
outErrorOn failure, the error will be written here.
Returns
True if the document was purged, false if it doesn't exist or the purge failed.

◆ CBLDatabase_SaveDocument()

bool CBLDatabase_SaveDocument ( CBLDatabase db,
CBLDocument doc,
CBLError *_cbl_nullable  outError 
)

Saves a (mutable) document to the database.

Warning
If a newer revision has been saved since doc was loaded, it will be overwritten by this one. This can lead to data loss! To avoid this, call CBLDatabase_SaveDocumentWithConcurrencyControl or CBLDatabase_SaveDocumentWithConflictHandler instead.
Parameters
dbThe database to save to.
docThe mutable document to save.
outErrorOn failure, the error will be written here.
Returns
True on success, false on failure.

◆ CBLDatabase_SaveDocumentWithConcurrencyControl()

bool CBLDatabase_SaveDocumentWithConcurrencyControl ( CBLDatabase db,
CBLDocument doc,
CBLConcurrencyControl  concurrency,
CBLError *_cbl_nullable  outError 
)

Saves a (mutable) document to the database.

If a conflicting revision has been saved since doc was loaded, the concurrency parameter specifies whether the save should fail, or the conflicting revision should be overwritten with the revision being saved. If you need finer-grained control, call CBLDatabase_SaveDocumentWithConflictHandler instead.

Parameters
dbThe database to save to.
docThe mutable document to save.
concurrencyConflict-handling strategy (fail or overwrite).
outErrorOn failure, the error will be written here.
Returns
True on success, false on failure.

◆ CBLDatabase_SaveDocumentWithConflictHandler()

bool CBLDatabase_SaveDocumentWithConflictHandler ( CBLDatabase db,
CBLDocument doc,
CBLConflictHandler  conflictHandler,
void *_cbl_nullable  context,
CBLError *_cbl_nullable  outError 
)

Saves a (mutable) document to the database, allowing for custom conflict handling in the event that the document has been updated since doc was loaded.

Parameters
dbThe database to save to.
docThe mutable document to save.
conflictHandlerThe callback to be invoked if there is a conflict.
contextAn arbitrary value to be passed to the conflictHandler.
outErrorOn failure, the error will be written here.
Returns
True on success, false on failure.

◆ CBLDatabase_SetDocumentExpiration()

bool CBLDatabase_SetDocumentExpiration ( CBLDatabase db,
FLSlice  docID,
CBLTimestamp  expiration,
CBLError *_cbl_nullable  outError 
)

Sets or clears the expiration time of a document.

Parameters
dbThe database.
docIDThe ID of the document.
expirationThe expiration time as a CBLTimestamp (milliseconds since Unix epoch), or 0 if the document should never expire.
outErrorOn failure, an error is written here.
Returns
True on success, false on failure.

◆ CBLDocument_Create()

_cbl_warn_unused CBLDocument * CBLDocument_Create ( void  )

Creates a new, empty document in memory, with a randomly-generated unique ID.

It will not be added to a database until saved.

Returns
The new mutable document instance.

◆ CBLDocument_CreateJSON()

_cbl_warn_unused FLSliceResult CBLDocument_CreateJSON ( const CBLDocument )

Returns a document's properties as JSON.

Note
You are responsible for releasing the result by calling FLSliceResult_Release.

◆ CBLDocument_CreateWithID()

_cbl_warn_unused CBLDocument * CBLDocument_CreateWithID ( FLString  docID)

Creates a new, empty document in memory, with the given ID.

It will not be added to a database until saved.

Note
If the given ID conflicts with a document already in the database, that will not be apparent until this document is saved. At that time, the result depends on the conflict handling mode used when saving; see the save functions for details.
Parameters
docIDThe ID of the new document, or NULL to assign a new unique ID.
Returns
The new mutable document instance.

◆ CBLDocument_ID()

FLString CBLDocument_ID ( const CBLDocument )

Returns a document's ID.

◆ CBLDocument_MutableCopy()

_cbl_warn_unused CBLDocument * CBLDocument_MutableCopy ( const CBLDocument original)

Creates a new mutable CBLDocument instance that refers to the same document as the original.

If the original document has unsaved changes, the new one will also start out with the same changes; but mutating one document thereafter will not affect the other.

Note
You must release the new reference when you're done with it. Similarly, the original document still exists and must also be released when you're done with it.

◆ CBLDocument_MutableProperties()

FLMutableDict CBLDocument_MutableProperties ( CBLDocument )

Returns a mutable document's properties as a mutable dictionary.

You may modify this dictionary and then call CBLDatabase_SaveDocument to persist the changes.

Note
The dictionary object is owned by the document; you do not need to release it.
Every call to this function returns the same mutable collection. This is the same collection returned by CBLDocument_Properties.
When accessing nested collections inside the properties as a mutable collection for modification, use FLMutableDict_GetMutableDict or FLMutableDict_GetMutableArray.
Warning
When the document is released, this reference to the properties becomes invalid. If you need to use any properties after releasing the document, you must retain them by calling FLValue_Retain (and of course later release them.)

◆ CBLDocument_Properties()

FLDict CBLDocument_Properties ( const CBLDocument )

Returns a document's properties as a dictionary.

Note
The dictionary object is owned by the document; you do not need to release it.
Warning
When the document is released, this reference to the properties becomes invalid. If you need to use any properties after releasing the document, you must retain them by calling FLValue_Retain (and of course later release them.)
This dictionary reference is immutable, but if the document is mutable the underlying dictionary itself is mutable and could be modified through a mutable reference obtained via CBLDocument_MutableProperties. If you need to preserve the properties, call FLDict_MutableCopy to make a deep copy.

◆ CBLDocument_Release()

static void CBLDocument_Release ( const CBLDocument t)
inlinestatic

◆ CBLDocument_Retain()

static const CBLDocument * CBLDocument_Retain ( const CBLDocument t)
inlinestatic

◆ CBLDocument_RevisionID()

FLString CBLDocument_RevisionID ( const CBLDocument )

Returns a document's revision ID, which is a short opaque string that's guaranteed to be unique to every change made to the document.

If the document doesn't exist yet, this function returns NULL.

◆ CBLDocument_Sequence()

uint64_t CBLDocument_Sequence ( const CBLDocument )

Returns a document's current sequence in the local database.

This number increases every time the document is saved, and a more recently saved document will have a greater sequence number than one saved earlier, so sequences may be used as an abstract 'clock' to tell relative modification times.

◆ CBLDocument_SetJSON()

bool CBLDocument_SetJSON ( CBLDocument ,
FLSlice  json,
CBLError *_cbl_nullable  outError 
)

Sets a mutable document's properties from a JSON string.

◆ CBLDocument_SetProperties()

void CBLDocument_SetProperties ( CBLDocument ,
FLMutableDict  properties 
)

Sets a mutable document's properties.

Call CBLDatabase_SaveDocument to persist the changes.

Note
The dictionary object will be retained by the document. You are responsible for releasing any retained reference(s) you have to it.

Variable Documentation

◆ kCBLTypeProperty

CBL_PUBLIC const FLSlice kCBLTypeProperty
extern

"@type"