A CBLDocument is essentially a JSON object with an ID string that's unique in its database.
More...
|
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...
|
|
|
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...
|
|
A CBLDocument is essentially a JSON object with an ID string that's unique in its database.
◆ CBLConflictHandler
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
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. |
◆ CBLConcurrencyControl
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.
|
◆ CBLDatabase_AddDocumentChangeListener()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
Returns a document's properties as JSON.
- Note
- You are responsible for releasing the result by calling FLSliceResult_Release.
◆ CBLDocument_CreateWithID()
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()
◆ CBLDocument_MutableCopy()
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()
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()
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()
◆ CBLDocument_RevisionID()
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()
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()
Sets a mutable document's properties from a JSON string.
◆ CBLDocument_SetProperties()
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.
◆ kCBLTypeProperty