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.

Variables
CBL_PUBLIC const FLSlice	kCBLTypeProperty
	"@type"

Document lifecycle
enum	CBLConcurrencyControl : uint8_t { kCBLConcurrencyControlLastWriteWins , kCBLConcurrencyControlFailOnConflict }
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.
_cbl_warn_unused const CBLDocument *_cbl_nullable	CBLDatabase_GetDocument (const CBLDatabase *database, FLString docID, CBLError *_cbl_nullable outError)
	Reads a document from the default collection in an immutable form.
CBLINLINE const CBLDocument *	CBLDocument_Retain (const CBLDocument *_cbl_nullable t)
CBLINLINE void	CBLDocument_Release (const CBLDocument *_cbl_nullable t)
bool	CBLDatabase_SaveDocument (CBLDatabase *db, CBLDocument *doc, CBLError *_cbl_nullable outError)
	Saves a (mutable) document to the default collection.
bool	CBLDatabase_SaveDocumentWithConcurrencyControl (CBLDatabase *db, CBLDocument *doc, CBLConcurrencyControl concurrency, CBLError *_cbl_nullable outError)
	Saves a (mutable) document to the default collection.
bool	CBLDatabase_SaveDocumentWithConflictHandler (CBLDatabase *db, CBLDocument *doc, CBLConflictHandler conflictHandler, void *_cbl_nullable context, CBLError *_cbl_nullable outError)
	Saves a (mutable) document to the default collection, allowing for custom conflict handling in the event that the document has been updated since doc was loaded.
bool	CBLDatabase_DeleteDocument (CBLDatabase *db, const CBLDocument *document, CBLError *_cbl_nullable outError)
	Deletes a document from the default collection.
bool	CBLDatabase_DeleteDocumentWithConcurrencyControl (CBLDatabase *db, const CBLDocument *document, CBLConcurrencyControl concurrency, CBLError *_cbl_nullable outError)
	Deletes a document from the default collection.
bool	CBLDatabase_PurgeDocument (CBLDatabase *db, const CBLDocument *document, CBLError *_cbl_nullable outError)
	Purges a document from the default collection.
bool	CBLDatabase_PurgeDocumentByID (CBLDatabase *database, FLString docID, CBLError *_cbl_nullable outError)
	Purges a document by its ID from the default collection.

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.
_cbl_warn_unused CBLListenerToken *	CBLDatabase_AddDocumentChangeListener (const CBLDatabase *db, FLString docID, CBLDocumentChangeListener listener, void *_cbl_nullable context)
	Registers a document change listener callback.

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 CBLCollection_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 default collection in mutable form that can be updated and saved.
_cbl_warn_unused CBLDocument *	CBLDocument_Create (void)
	Creates a new, empty document in memory, with a randomly-generated unique ID.
_cbl_warn_unused CBLDocument *	CBLDocument_CreateWithID (FLString docID)
	Creates a new, empty document in memory, with the given ID.
_cbl_warn_unused CBLDocument *	CBLDocument_MutableCopy (const CBLDocument *original)
	Creates a new mutable CBLDocument instance that refers to the same document as the original.

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.
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.
uint64_t	CBLDocument_Sequence (const CBLDocument *)
	Returns a document's current sequence in the local database.
CBLCollection *_cbl_nullable	CBLDocument_Collection (const CBLDocument *)
	Returns a document's collection or NULL for the new document that hasn't been saved.
FLDict	CBLDocument_Properties (const CBLDocument *)
	Returns a document's properties as a dictionary.
FLMutableDict	CBLDocument_MutableProperties (CBLDocument *)
	Returns a mutable document's properties as a mutable dictionary.
void	CBLDocument_SetProperties (CBLDocument *, FLMutableDict properties)
	Sets a mutable document's properties.
_cbl_warn_unused FLSliceResult	CBLDocument_CreateJSON (const CBLDocument *)
	Returns a document's properties as JSON.
bool	CBLDocument_SetJSON (CBLDocument *, FLSlice json, CBLError *_cbl_nullable outError)
	Sets a mutable document's properties from a JSON string.
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.
bool	CBLDatabase_SetDocumentExpiration (CBLDatabase *db, FLSlice docID, CBLTimestamp expiration, CBLError *_cbl_nullable outError)
	Sets or clears the expiration time of a document.

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 CBLCollection_SaveDocumentWithConflictHandler.
documentBeingSaved	The document being saved (same as the parameter you passed to CBLCollection_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.

Deprecated : Use CBLCollectionChangeListener instead.

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

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.

Warning

Deprecated : Use CBLCollection_AddDocumentChangeListener on the default collection instead.

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 default collection.

Deletions are replicated.

Warning

You are still responsible for releasing the CBLDocument.

Deprecated : Use CBLCollection_DeleteDocument on the default collection instead.

Parameters

db	The database.
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 default collection.

Deletions are replicated.

Warning

You are still responsible for releasing the CBLDocument.

Deprecated : Use CBLCollection_DeleteDocumentWithConcurrencyControl on the default collection instead.

Parameters

db	The database.
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 default collection in an immutable form.

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.

Warning

Deprecated : Use CBLCollection_GetDocument on the default collection 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.

Warning

Deprecated : Use CBLCollection_GetDocumentExpiration instead.

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 default collection 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.

Warning

Deprecated : Use CBLCollection_GetMutableDocument on the default collection 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_PurgeDocument()

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

Purges a document from the default collection.

This removes all traces of the document. 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.

Deprecated : Use CBLCollection_PurgeDocument on the default collection instead.

Note

If you don't have the document in memory already, CBLDatabase_PurgeDocumentByID is a simpler shortcut.

Parameters

db	The database.
document	The document 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_PurgeDocumentByID()

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

Purges a document by its ID from the default collection.

Note

If no document with that ID exists, this function will return false but the error code will be zero.

Warning

Deprecated : Use CBLCollection_PurgeDocumentByID on the default collection instead.

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 default collection.

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.

Deprecated : Use CBLCollection_SaveDocument on the default collection instead.

Parameters

db	The database.
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 default collection.

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.

Warning

Deprecated : Use CBLCollection_SaveDocumentWithConcurrencyControl on the default collection instead.

Parameters

db	The database.
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 default collection, allowing for custom conflict handling in the event that the document has been updated since doc was loaded.

Warning

Deprecated : Use CBLCollection_SaveDocumentWithConflictHandler on the default collection instead.

Parameters

db	The database.
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.

Warning

Deprecated : Use CBLCollection_SetDocumentExpiration instead.

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_Collection()

CBLCollection *_cbl_nullable CBLDocument_Collection

(

const CBLDocument *

)

Returns a document's collection or NULL for the new document that hasn't been saved.

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 CBLCollection_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()

CBLINLINE void CBLDocument_Release

(

const CBLDocument *_cbl_nullable

t

)

CBLDocument_Retain()

CBLINLINE const CBLDocument * CBLDocument_Retain

(

const CBLDocument *_cbl_nullable

t

)

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 CBLCollection_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"