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 CBLDocument *	CBLDocument_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 CBLListenerToken *	CBLDatabase_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 CBLDocument *	CBLDocument_Create (void)
	Creates a new, empty document in memory, with a randomly-generated unique ID. More...

_cbl_warn_unused CBLDocument *	CBLDocument_CreateWithID (FLString docID)
	Creates a new, empty document in memory, with the given ID. More...

_cbl_warn_unused CBLDocument *	CBLDocument_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

context	The value of the `context` parameter you passed to CBLDatabase_SaveDocumentWithConflictHandler.
documentBeingSaved	The 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.
conflictingDocument	The 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

context	An arbitrary value given when the callback was registered.
db	The database containing the document.
docID	The 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

db	The database to observe.
docID	The ID of the document to observe.
listener	The callback to be invoked.
context	An 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

db	The database containing the document.
document	The document to delete.
outError	On 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

db	The database containing the document.
document	The document to delete.
concurrency	Conflict-handling strategy.
outError	On 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

database	The database.
docID	The ID of the document.
outError	On 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

db	The database.
docID	The ID of the document.
outError	On 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

database	The database.
docID	The ID of the document.
outError	On 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

db	The database containing the document.
document	The document to delete.
outError	On 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

database	The database.
docID	The document ID to purge.
outError	On 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

db	The database to save to.
doc	The mutable document to save.
outError	On 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

db	The database to save to.
doc	The mutable document to save.
concurrency	Conflict-handling strategy (fail or overwrite).
outError	On 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

db	The database to save to.
doc	The mutable document to save.
conflictHandler	The callback to be invoked if there is a conflict.
context	An arbitrary value to be passed to the `conflictHandler`.
outError	On 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

db	The database.
docID	The ID of the document.
expiration	The expiration time as a CBLTimestamp (milliseconds since Unix epoch), or 0 if the document should never expire.
outError	On 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

docID The 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"

Typedefs

Variables

Document lifecycle

Document listeners

Mutable documents

Document properties and metadata

Detailed Description

Typedef Documentation

◆ CBLConflictHandler

◆ CBLDocument

◆ CBLDocumentChangeListener

Enumeration Type Documentation

◆ CBLConcurrencyControl

Function Documentation

◆ CBLDatabase_AddDocumentChangeListener()

◆ CBLDatabase_DeleteDocument()

◆ CBLDatabase_DeleteDocumentWithConcurrencyControl()

◆ CBLDatabase_GetDocument()

◆ CBLDatabase_GetDocumentExpiration()

◆ CBLDatabase_GetMutableDocument()

◆ CBLDatabase_PurgeDocument()

◆ CBLDatabase_PurgeDocumentByID()

◆ CBLDatabase_SaveDocument()

◆ CBLDatabase_SaveDocumentWithConcurrencyControl()

◆ CBLDatabase_SaveDocumentWithConflictHandler()

◆ CBLDatabase_SetDocumentExpiration()

◆ CBLDocument_Create()

◆ CBLDocument_CreateJSON()

◆ CBLDocument_CreateWithID()

◆ CBLDocument_ID()

◆ CBLDocument_MutableCopy()

◆ CBLDocument_MutableProperties()

◆ CBLDocument_Properties()

◆ CBLDocument_Release()

◆ CBLDocument_Retain()

◆ CBLDocument_RevisionID()

◆ CBLDocument_Sequence()

◆ CBLDocument_SetJSON()

◆ CBLDocument_SetProperties()

Variable Documentation

◆ kCBLTypeProperty