Couchbase Lite C
Couchbase Lite C API
CBLDocument.h
Go to the documentation of this file.
1//
2// CBLDocument.h
3//
4// Copyright (c) 2018 Couchbase, Inc All rights reserved.
5//
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17//
18
19#pragma once
20#include "CBLBase.h"
21
23
30
40};
41
42
56typedef bool (*CBLConflictHandler)(void* _cbl_nullable context,
57 CBLDocument* _cbl_nullable documentBeingSaved,
58 const CBLDocument* _cbl_nullable conflictingDocument);
59
60
73 FLString docID,
74 CBLError* _cbl_nullable outError) CBLAPI;
75
77
89 CBLDocument* doc,
90 CBLError* _cbl_nullable outError) CBLAPI;
91
104 CBLDocument* doc,
105 CBLConcurrencyControl concurrency,
106 CBLError* _cbl_nullable outError) CBLAPI;
107
118 CBLDocument* doc,
119 CBLConflictHandler conflictHandler,
120 void* _cbl_nullable context,
121 CBLError* _cbl_nullable outError) CBLAPI;
122
131 const CBLDocument* document,
132 CBLError* _cbl_nullable outError) CBLAPI;
133
143 const CBLDocument* document,
144 CBLConcurrencyControl concurrency,
145 CBLError* _cbl_nullable outError) CBLAPI;
146
159 const CBLDocument* document,
160 CBLError* _cbl_nullable outError) CBLAPI;
161
171 FLString docID,
172 CBLError* _cbl_nullable outError) CBLAPI;
173
196 FLString docID,
197 CBLError* _cbl_nullable outError) CBLAPI;
198
204
214
222
235
240
246
249
260
272
278 FLMutableDict properties) CBLAPI;
279
284
287 FLSlice json,
288 CBLError* _cbl_nullable outError) CBLAPI;
289
301 FLSlice docID,
302 CBLError* _cbl_nullable outError) CBLAPI;
303
313 FLSlice docID,
314 CBLTimestamp expiration,
315 CBLError* _cbl_nullable outError) CBLAPI;
316
337typedef void (*CBLDocumentChangeListener)(void *context,
338 const CBLDatabase* db,
339 FLString docID);
340
351 FLString docID,
353 void* _cbl_nullable context) CBLAPI;
354
#define CBLAPI
Definition: CBL_Compat.h:104
#define _cbl_nullable
Definition: CBL_Compat.h:92
#define CBL_CAPI_BEGIN
Definition: CBL_Compat.h:105
#define CBL_CAPI_END
Definition: CBL_Compat.h:106
#define CBL_PUBLIC
Definition: CBL_Compat.h:123
#define CBL_ENUM(_type, _name)
Definition: CBL_Compat.h:62
#define _cbl_warn_unused
Definition: CBL_Compat.h:40
struct CBLCollection CBLCollection
A collection, a document container.
Definition: CBLBase.h:194
struct CBLDatabase CBLDatabase
A connection to an open database.
Definition: CBLBase.h:182
_cbl_warn_unused FLSliceResult CBLDocument_CreateJSON(const CBLDocument *)
Returns a document's properties as JSON.
bool CBLDatabase_DeleteDocumentWithConcurrencyControl(CBLDatabase *db, const CBLDocument *document, CBLConcurrencyControl concurrency, CBLError *_cbl_nullable outError)
Deletes a document from the default collection.
_cbl_warn_unused CBLDocument * CBLDocument_MutableCopy(const CBLDocument *original)
Creates a new mutable CBLDocument instance that refers to the same document as the original.
_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.
_cbl_warn_unused CBLDocument * CBLDocument_Create(void)
Creates a new, empty document in memory, with a randomly-generated unique ID.
CBLConcurrencyControl
Conflict-handling options when saving or deleting a document.
Definition: CBLDocument.h:35
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.
FLString CBLDocument_ID(const CBLDocument *)
Returns a document's ID.
bool CBLDocument_SetJSON(CBLDocument *, FLSlice json, CBLError *_cbl_nullable outError)
Sets a mutable document's properties from a JSON string.
CBLCollection *_cbl_nullable CBLDocument_Collection(const CBLDocument *)
Returns a document's collection or NULL for the new document that hasn't been saved.
CBL_PUBLIC const FLSlice kCBLTypeProperty
"@type"
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.
Definition: CBLDocument.h:56
bool CBLDatabase_PurgeDocumentByID(CBLDatabase *database, FLString docID, CBLError *_cbl_nullable outError)
Purges a document by its ID from the default collection.
struct CBLDocument CBLDocument
An in-memory copy of a document.
Definition: CBLBase.h:203
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 ev...
void(* CBLDocumentChangeListener)(void *context, const CBLDatabase *db, FLString docID)
A document change listener callback, invoked after a specific document is changed on disk.
Definition: CBLDocument.h:337
uint64_t CBLDocument_Sequence(const CBLDocument *)
Returns a document's current sequence in the local database.
FLString CBLDocument_RevisionID(const CBLDocument *)
Returns a document's revision ID, which is a short opaque string that's guaranteed to be unique to ev...
FLMutableDict CBLDocument_MutableProperties(CBLDocument *)
Returns a mutable document's properties as a mutable dictionary.
_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.
bool CBLDatabase_SetDocumentExpiration(CBLDatabase *db, FLSlice docID, CBLTimestamp expiration, CBLError *_cbl_nullable outError)
Sets or clears the expiration time of a document.
_cbl_warn_unused CBLListenerToken * CBLDatabase_AddDocumentChangeListener(const CBLDatabase *db, FLString docID, CBLDocumentChangeListener listener, void *_cbl_nullable context)
Registers a document change listener callback.
bool CBLDatabase_DeleteDocument(CBLDatabase *db, const CBLDocument *document, CBLError *_cbl_nullable outError)
Deletes a document from the default collection.
FLDict CBLDocument_Properties(const CBLDocument *)
Returns a document's properties as a dictionary.
bool CBLDatabase_SaveDocumentWithConcurrencyControl(CBLDatabase *db, CBLDocument *doc, CBLConcurrencyControl concurrency, CBLError *_cbl_nullable outError)
Saves a (mutable) document to the default collection.
_cbl_warn_unused CBLDocument * CBLDocument_CreateWithID(FLString docID)
Creates a new, empty document in memory, with the given ID.
void CBLDocument_SetProperties(CBLDocument *, FLMutableDict properties)
Sets a mutable document's properties.
bool CBLDatabase_SaveDocument(CBLDatabase *db, CBLDocument *doc, CBLError *_cbl_nullable outError)
Saves a (mutable) document to the default collection.
bool CBLDatabase_PurgeDocument(CBLDatabase *db, const CBLDocument *document, CBLError *_cbl_nullable outError)
Purges a document from the default collection.
@ kCBLConcurrencyControlLastWriteWins
The current save/delete will overwrite a conflicting revision if there is a conflict.
Definition: CBLDocument.h:37
@ kCBLConcurrencyControlFailOnConflict
The current save/delete will fail if there is a conflict.
Definition: CBLDocument.h:39
struct CBLListenerToken CBLListenerToken
An opaque 'cookie' representing a registered listener callback.
Definition: CBLBase.h:281
int64_t CBLTimestamp
A date/time representation used for document expiration (and in date/time queries....
Definition: CBLBase.h:123
#define CBL_REFCOUNTED(TYPE, NAME)
Definition: CBLBase.h:170
struct _FLDict * FLMutableDict
A reference to a mutable dictionary.
Definition: FLBase.h:40
const struct _FLDict * FLDict
A reference to a dictionary (map) value.
Definition: FLBase.h:37
A struct holding information about an error.
Definition: CBLBase.h:104
A simple reference to a block of memory.
Definition: FLSlice.h:45
A heap-allocated block of memory returned from an API call.
Definition: FLSlice.h:63