Documents

Data Structures
struct	C4Revision
	Describes a revision of a document. More...
struct	C4DocPutRequest
	Parameters for adding a revision using c4doc_put. More...

Typedefs
typedef uint32_t	C4RemoteID
	Identifies a remote database being replicated with.

Enumerations
enum	C4DocumentFlags : uint32_t { kDocDeleted = 0x01 , kDocConflicted = 0x02 , kDocHasAttachments = 0x04 , kDocExists = 0x1000 }
enum	C4RevisionFlags : uint8_t {   kRevDeleted = 0x01 , kRevLeaf = 0x02 , kRevNew = 0x04 , kRevHasAttachments = 0x08 ,   kRevKeepBody = 0x10 , kRevIsConflict = 0x20 , kRevClosed = 0x40 , kRevPurged = 0x80 }
enum	C4DocContentLevel : uint8_t { kDocGetMetadata , kDocGetCurrentRev , kDocGetAll , kDocGetUpgraded }

Creating and Updating Documents
typedef C4SliceResult(*	C4DocDeltaApplier) (void *context, C4Document *doc, C4Slice delta, C4RevisionFlags *revFlags, C4Error *outError)
	Optional callback to c4doc_put that generates the new revision body, based on an earlier revision body and the body of the C4DocPutRequest.

Fleece-related
CBL_CORE_API FLDict	c4doc_getProperties (C4Document *)
	Returns the properties of the selected revision, i.e.
NODISCARD CBL_CORE_API FLDoc	c4doc_createFleeceDoc (C4Document *)
	Returns a Fleece document reference created from the selected revision.
NODISCARD CBL_CORE_API bool	c4doc_resolveConflict2 (C4Document *doc, C4String winningRevID, C4String losingRevID, FLDict mergedProperties, C4RevisionFlags mergedFlags, C4Error *error)
	Resolves a conflict between two leaf revisions.
CBL_CORE_API C4Document *	c4doc_containingValue (FLValue value)
	Returns the C4Document, if any, that contains the given Fleece value.
CBL_CORE_API bool	c4doc_isOldMetaProperty (C4String prop)
	Returns true if this is the name of a 1.x metadata property ("_id", "_rev", "_deleted".) Does NOT return true for "_attachments" because that property isn't obsolete.
CBL_CORE_API bool	c4doc_hasOldMetaProperties (FLDict doc)
	Returns true if the document contains 1.x metadata properties at top level.
CBL_CORE_API C4SliceResult	c4doc_encodeStrippingOldMetaProperties (FLDict doc, FLSharedKeys sk, C4Error *outError)
	Re-encodes to Fleece, without any 1.x metadata properties.
NODISCARD CBL_CORE_API bool	c4doc_getDictBlobKey (FLDict dict, C4BlobKey *outKey)
	Decodes the dict's "digest" property to a C4BlobKey.
NODISCARD CBL_CORE_API bool	c4doc_dictIsBlob (FLDict dict, C4BlobKey *outKey)
	Returns true if the given dictionary is a [reference to a] blob; if so, gets its key.
CBL_CORE_API bool	c4doc_dictContainsBlobs (FLDict dict)
	Returns true if the given dictionary is a [reference to a] blob;.
CBL_CORE_API C4SliceResult	c4doc_getBlobData (FLDict dict, C4BlobStore *blobStore, C4Error *outError)
	Returns the contents of a blob dictionary, whether they're inline in the "data" property, or indirectly referenced via the "digest" property.
CBL_CORE_API bool	c4doc_blobIsCompressible (FLDict blobDict)
	Given a dictionary that's a reference to a blob, determines whether it's worth trying to compress the blob's data.
CBL_CORE_API C4StringResult	c4doc_bodyAsJSON (C4Document *doc, bool canonical, C4Error *outError)
	Translates the body of the selected revision from Fleece to JSON.
NODISCARD CBL_CORE_API FLEncoder	c4db_createFleeceEncoder (C4Database *db)
	Creates a Fleece encoder for creating documents for a given database.
CBL_CORE_API FLEncoder	c4db_getSharedFleeceEncoder (C4Database *db)
	Returns a shared Fleece encoder for creating documents for a given database.
CBL_CORE_API C4SliceResult	c4db_encodeJSON (C4Database *, C4String jsonData, C4Error *outError)
	Encodes JSON data to Fleece, to store into a document.
CBL_CORE_API FLSharedKeys	c4db_getFLSharedKeys (C4Database *db)
	Returns the FLSharedKeys object used by the given database.
#define	kC4ObjectTypeProperty   "@type"
	The sub-document property that identifies it as a special type of object.
#define	kC4ObjectType_Blob   "blob"
	Value of kC4ObjectTypeProperty that denotes a blob.
#define	kC4BlobDigestProperty   "digest"
	Blob dict property containing a digest of the data.
#define	kC4BlobDataProperty   "data"
	Blob dict property containing the data itself.
#define	kC4LegacyAttachmentsProperty   "_attachments"
	Top-level document property whose value is a CBL 1.x / CouchDB attachments container.
#define	kC4ObjectType_Encryptable   "encryptable"
	Value of kC4ObjectTypeProperty that denotes an encryptable value.
#define	kC4EncryptableValueProperty   "value"
	Encryptable-value property containing the actual value; may be any type.

Lifecycle
CBL_CORE_API char *	c4doc_generateID (char *buffer, size_t bufferSize)
	Generates a random 23-byte C string suitable for use as a unique new document ID.
NODISCARD CBL_CORE_API C4Document *	c4db_getDoc (C4Database *database, C4String docID, bool mustExist, C4DocContentLevel content, C4Error *outError)
	Gets a document from the database given its ID.
NODISCARD CBL_CORE_API C4Document *	c4doc_get (C4Database *database, C4String docID, bool mustExist, C4Error *outError)
	Gets a document from the database given its ID (semi-deprecated).
NODISCARD CBL_CORE_API C4Document *	c4doc_getBySequence (C4Database *database, C4SequenceNumber, C4Error *outError)
	Gets a document from the database given its sequence number.
NODISCARD CBL_CORE_API bool	c4doc_save (C4Document *doc, uint32_t maxRevTreeDepth, C4Error *outError)
	Saves changes to a C4Document.
#define	kC4GeneratedIDLength   23

Revisions
CBL_CORE_API bool	c4doc_isRevRejected (C4Document *doc)
NODISCARD CBL_CORE_API bool	c4doc_selectRevision (C4Document *doc, C4String revID, bool withBody, C4Error *outError)
	Selects a specific revision of a document (or no revision, if revID is NULL.)
CBL_CORE_API bool	c4doc_selectCurrentRevision (C4Document *doc)
	Selects the current revision of a document.
NODISCARD CBL_CORE_API bool	c4doc_loadRevisionBody (C4Document *doc, C4Error *outError)
	Populates the body field of a doc's selected revision, if it was initially loaded without its body.
CBL_CORE_API bool	c4doc_hasRevisionBody (C4Document *doc)
	Returns true if the body of the selected revision is available, i.e.
CBL_CORE_API C4Slice	c4doc_getRevisionBody (C4Document *doc)
	Returns the body (encoded Fleece data) of the selected revision, if available.
CBL_CORE_API C4SliceResult	c4doc_getRevisionHistory (C4Document *doc, unsigned maxRevs, const C4String backToRevs[], unsigned backToRevsCount)
	Returns a string encoding the selected revision's history, as comma-separate revision/version IDs in reverse chronological order.
CBL_CORE_API C4SliceResult	c4doc_getSelectedRevIDGlobalForm (C4Document *doc)
	Returns the selected revision's ID in a form that will make sense to another peer/server.
NODISCARD CBL_CORE_API bool	c4doc_selectParentRevision (C4Document *doc)
	Selects the parent of the selected revision, if it's known, else returns false.
NODISCARD CBL_CORE_API bool	c4doc_selectNextRevision (C4Document *doc)
	Selects the next revision in priority order.
NODISCARD CBL_CORE_API bool	c4doc_selectNextLeafRevision (C4Document *doc, bool includeDeleted, bool withBody, C4Error *outError)
	Selects the next leaf revision; like selectNextRevision but skips over non-leaves.
NODISCARD CBL_CORE_API bool	c4doc_selectCommonAncestorRevision (C4Document *doc, C4String rev1ID, C4String rev2ID)
	Selects the common ancestor of two revisions.
CBL_CORE_API C4RemoteID	c4db_getRemoteDBID (C4Database *db, C4String remoteAddress, bool canCreate, C4Error *outError)
	Looks up or creates a numeric ID identifying a remote database, for use with c4doc_getRemoteAncestor() and c4doc_setRemoteAncestor().
CBL_CORE_API C4SliceResult	c4db_getRemoteDBAddress (C4Database *db, C4RemoteID remoteID)
	Given a remote database ID, returns its replication URL / unique identifier.
CBL_CORE_API C4SliceResult	c4doc_getRemoteAncestor (C4Document *doc, C4RemoteID remoteDatabase)
	Returns the revision ID that has been marked as current for the given remote database.
NODISCARD CBL_CORE_API bool	c4doc_setRemoteAncestor (C4Document *doc, C4RemoteID remoteDatabase, C4String revID, C4Error *error)
	Marks a revision as current for the given remote database.
CBL_CORE_API unsigned	c4rev_getGeneration (C4String revID)
	Given a tree-based revision ID, returns its generation number (the decimal number before the hyphen), or zero if it's unparseable.
CBL_CORE_API uint64_t	c4rev_getTimestamp (C4String revID)
	Given a revision ID that's a Version (of the form time@peer), returns its timestamp.
CBL_CORE_API bool	c4rev_equal (C4Slice rev1, C4Slice rev2)
	Returns true if two revision IDs are equivalent.
NODISCARD CBL_CORE_API int32_t	c4doc_purgeRevision (C4Document *doc, C4String revID, C4Error *outError)
	Removes a branch from a document's history.
NODISCARD CBL_CORE_API bool	c4doc_resolveConflict (C4Document *doc, C4String winningRevID, C4String losingRevID, C4Slice mergedBody, C4RevisionFlags mergedFlags, C4Error *error)
	Resolves a conflict between two leaf revisions, by deleting one of them and optionally adding a new merged revision as a child of the other.

Purging and Expiration
CBL_CORE_API bool	c4db_purgeDoc (C4Database *database, C4String docID, C4Error *outError)
	Removes all trace of a document and its revisions from the database.
CBL_CORE_API bool	c4doc_setExpiration (C4Database *db, C4String docID, C4Timestamp timestamp, C4Error *outError)
	Sets an expiration date on a document.
CBL_CORE_API C4Timestamp	c4doc_getExpiration (C4Database *db, C4String docID, C4Error *outError)
	Returns the expiration time of a document, if one has been set, else 0.

Creating and Updating Documents
CBL_CORE_API C4Document *	c4doc_put (C4Database *database, const C4DocPutRequest *request, size_t *outCommonAncestorIndex, C4Error *outError)
	A high-level Put operation, to insert a new or downloaded revision.
CBL_CORE_API C4Document *	c4doc_create (C4Database *db, C4String docID, C4Slice body, C4RevisionFlags revisionFlags, C4Error *error)
	Convenience function to create a new document.
CBL_CORE_API C4Document *	c4doc_update (C4Document *doc, C4Slice revisionBody, C4RevisionFlags revisionFlags, C4Error *error)
	Adds a revision to a document already in memory as a C4Document.

Detailed Description

Macro Definition Documentation

kC4BlobDataProperty

#define kC4BlobDataProperty   "data"

Blob dict property containing the data itself.

(Required if "digest" is absent)

kC4BlobDigestProperty

#define kC4BlobDigestProperty   "digest"

Blob dict property containing a digest of the data.

(Required if "data" is absent)

kC4EncryptableValueProperty

#define kC4EncryptableValueProperty   "value"

Encryptable-value property containing the actual value; may be any type.

(Required.)

kC4GeneratedIDLength

#define kC4GeneratedIDLength   23

kC4LegacyAttachmentsProperty

#define kC4LegacyAttachmentsProperty   "_attachments"

Top-level document property whose value is a CBL 1.x / CouchDB attachments container.

kC4ObjectType_Blob

#define kC4ObjectType_Blob   "blob"

Value of kC4ObjectTypeProperty that denotes a blob.

kC4ObjectType_Encryptable

#define kC4ObjectType_Encryptable   "encryptable"

Value of kC4ObjectTypeProperty that denotes an encryptable value.

kC4ObjectTypeProperty

#define kC4ObjectTypeProperty   "@type"

The sub-document property that identifies it as a special type of object.

For example, a blob is represented as {"@type":"blob", "digest":"xxxx", ...}

Typedef Documentation

C4DocDeltaApplier

typedef C4SliceResult(* C4DocDeltaApplier) (void *context, C4Document *doc, C4Slice delta, C4RevisionFlags *revFlags, C4Error *outError)

Optional callback to c4doc_put that generates the new revision body, based on an earlier revision body and the body of the C4DocPutRequest.

It's intended for use when the new revision is specified as a delta.

Parameters

context	The same value given in the C4DocPutRequest's deltaCBContext field.
doc	The document; its selected revision is the one requested in the deltaSourceRevID.
delta	The contents of the request's body or allocedBody.
revFlags	If not nullptr, its value may be updated after the delta is applied.
outError	If the callback fails, store an error here if it's non-NULL.

Returns

The body to store in the new revision, or a null slice on failure.

C4RemoteID

typedef uint32_t C4RemoteID

Identifies a remote database being replicated with.

Enumeration Type Documentation

C4DocContentLevel

enum C4DocContentLevel : uint8_t

Enumerator
kDocGetMetadata	Only get revID and flags.
kDocGetCurrentRev	Get current revision body but not other revisions/remotes.
kDocGetAll	Get everything.
kDocGetUpgraded	Get everything, upgrade to latest format (version vectors)

C4DocumentFlags

enum C4DocumentFlags : uint32_t

Enumerator
kDocDeleted	The document's current revision is deleted.
kDocConflicted	The document is in conflict.
kDocHasAttachments	The document's current revision has attachments.
kDocExists	The document exists (i.e. has revisions.)

C4RevisionFlags

enum C4RevisionFlags : uint8_t

Enumerator
kRevDeleted	Is this revision a deletion/tombstone?
kRevLeaf	Is this revision a leaf (no children?)
kRevNew	Has this rev been inserted since the doc was read?
kRevHasAttachments	Does this rev's body contain attachments?
kRevKeepBody	Revision's body should not be discarded when non-leaf.
kRevIsConflict	Unresolved conflicting revision; will never be current.
kRevClosed	Rev is the (deleted) end of a closed conflicting branch.
kRevPurged	Revision is purged (this flag is never stored in the db)

Function Documentation

c4db_createFleeceEncoder()

NODISCARD CBL_CORE_API FLEncoder c4db_createFleeceEncoder

(

C4Database *

db

)

Creates a Fleece encoder for creating documents for a given database.

Note

The caller must use a lock for Database when this function is called.

c4db_encodeJSON()

CBL_CORE_API C4SliceResult c4db_encodeJSON	(	C4Database *	,
		C4String	jsonData,
		C4Error *	outError )

Encodes JSON data to Fleece, to store into a document.

Note

The caller must use a lock for Database when this function is called.

c4db_getDoc()

NODISCARD CBL_CORE_API C4Document * c4db_getDoc	(	C4Database *	database,
		C4String	docID,
		bool	mustExist,
		C4DocContentLevel	content,
		C4Error *	outError )

Gets a document from the database given its ID.

The current revision is selected (if the document exists.) You must call c4doc_release() when finished with the document.

Note

The caller must use a lock for Database when this function is called.

Parameters

database	The database to read from.
docID	The document's ID.
mustExist	Governs behavior if no document with that ID exists. If true, the call fails with error kC4NotFound. If false, a C4Document with no contents is returned.
content	How much content to retrieve: metadata only, current revision, or all revisions.
outError	On failure, error information is stored here.

Returns

A new C4Document instance (which must be released), or NULL.

c4db_getFLSharedKeys()

CBL_CORE_API FLSharedKeys c4db_getFLSharedKeys

(

C4Database *

db

)

Returns the FLSharedKeys object used by the given database.

Note

The caller must use a lock for Database when this function is called.

c4db_getRemoteDBAddress()

CBL_CORE_API C4SliceResult c4db_getRemoteDBAddress	(	C4Database *	db,
		C4RemoteID	remoteID )

Given a remote database ID, returns its replication URL / unique identifier.

Note

The caller must use a lock for Database when this function is called.

Parameters

db	The database.
remoteID	The ID assigned to the remote database.

Returns

The URL/identifier, or a null slice if not found.

c4db_getRemoteDBID()

CBL_CORE_API C4RemoteID c4db_getRemoteDBID	(	C4Database *	db,
		C4String	remoteAddress,
		bool	canCreate,
		C4Error *	outError )

Looks up or creates a numeric ID identifying a remote database, for use with c4doc_getRemoteAncestor() and c4doc_setRemoteAncestor().

Note

The caller must use a lock for Database when this function is called.

Parameters

db	The database.
remoteAddress	The replication URL of the remote db, or its other unique identifier.
canCreate	If true, a new identifier will be created if one doesn't exist.
outError	Error information is stored here.

Returns

The ID, or 0 on error.

c4db_getSharedFleeceEncoder()

CBL_CORE_API FLEncoder c4db_getSharedFleeceEncoder

(

C4Database *

db

)

Returns a shared Fleece encoder for creating documents for a given database.

DO NOT FREE THIS ENCODER. Instead, call FLEncoder_Reset() when finished.

Note

The caller must use a lock for Database when this function is called.

c4db_purgeDoc()

CBL_CORE_API bool c4db_purgeDoc	(	C4Database *	database,
		C4String	docID,
		C4Error *	outError )

Removes all trace of a document and its revisions from the database.

Note

The caller must use a lock for Database when this function is called.

c4doc_blobIsCompressible()

CBL_CORE_API bool c4doc_blobIsCompressible

(

FLDict

blobDict

)

Given a dictionary that's a reference to a blob, determines whether it's worth trying to compress the blob's data.

This is done by examining the "encoding" and "content_type" properties and using heuristics to detect types that are already compressed, like gzip or JPEG. If no warning flags are found it will return true.

Note

The caller must use a lock for Database when this function is called.

Assume blobDict is obtained from the database.

c4doc_bodyAsJSON()

CBL_CORE_API C4StringResult c4doc_bodyAsJSON	(	C4Document *	doc,
		bool	canonical,
		C4Error *	outError )

Translates the body of the selected revision from Fleece to JSON.

Note

The caller must use a lock for Database when this function is called.

c4doc_containingValue()

CBL_CORE_API C4Document * c4doc_containingValue

(

FLValue

value

)

Returns the C4Document, if any, that contains the given Fleece value.

c4doc_create()

CBL_CORE_API C4Document * c4doc_create	(	C4Database *	db,
		C4String	docID,
		C4Slice	body,
		C4RevisionFlags	revisionFlags,
		C4Error *	error )

Convenience function to create a new document.

This just a wrapper around c4doc_put. If the document already exists, it will fail with the error kC4ErrorConflict.

Note

The caller must use a lock for Database when this function is called.

Parameters

db	The database to create the document in
docID	Document ID to create; if null, a UUID will be generated
body	Body of the document
revisionFlags	The flags of the new revision
error	Information about any error that occurred

Returns

On success, a new C4Document with the new revision selected; else NULL.

c4doc_createFleeceDoc()

NODISCARD CBL_CORE_API FLDoc c4doc_createFleeceDoc

(

C4Document *

)

Returns a Fleece document reference created from the selected revision.

Caller must release the reference!

Note

The caller must use a lock for Database when this function is called.

c4doc_dictContainsBlobs()

CBL_CORE_API bool c4doc_dictContainsBlobs

(

FLDict

dict

)

Returns true if the given dictionary is a [reference to a] blob;.

Note

The caller must use a lock for Database when this function is called.

Assume dict is obtained from the database.

c4doc_dictIsBlob()

NODISCARD CBL_CORE_API bool c4doc_dictIsBlob	(	FLDict	dict,
		C4BlobKey *	outKey )

Returns true if the given dictionary is a [reference to a] blob; if so, gets its key.

(This function cannot recognize child dictionaries of "_attachments", because it's not possible to look at the parent of a Fleece value.)

Note

The caller must use a lock for Database when this function is called.

Assume dict is obtained from the database.

c4doc_encodeStrippingOldMetaProperties()

CBL_CORE_API C4SliceResult c4doc_encodeStrippingOldMetaProperties	(	FLDict	doc,
		FLSharedKeys	sk,
		C4Error *	outError )

Re-encodes to Fleece, without any 1.x metadata properties.

Old-style attachments that don't refer to blobs will be removed; others are kept.

Note

This function is thread-safe.

c4doc_generateID()

CBL_CORE_API char * c4doc_generateID	(	char *	buffer,
		size_t	bufferSize )

Generates a random 23-byte C string suitable for use as a unique new document ID.

Parameters

buffer	Where to write the string.
bufferSize	Size of the buffer (must be at least kC4GeneratedIDLength + 1)

Returns

A pointer to the string in the buffer, or NULL if the buffer is too small.

c4doc_get()

NODISCARD CBL_CORE_API C4Document * c4doc_get	(	C4Database *	database,
		C4String	docID,
		bool	mustExist,
		C4Error *	outError )

Gets a document from the database given its ID (semi-deprecated).

This is the same as c4db_getDoc with content equal to kDocGetCurrentRev.

Note

The caller must use a lock for Database when this function is called.

c4doc_getBlobData()

CBL_CORE_API C4SliceResult c4doc_getBlobData	(	FLDict	dict,
		C4BlobStore *	blobStore,
		C4Error *	outError )

Returns the contents of a blob dictionary, whether they're inline in the "data" property, or indirectly referenced via the "digest" property.

Note

The caller must use a lock for Database when this function is called.

Assume dict is obtained from the database.

You can omit the C4BlobStore, but if the blob has no inline data the function will give up and return a null slice (and clear the error, since this isn't a failure.)

Parameters

dict	A blob dictionary.
blobStore	The database's BlobStore, or NULL to suppress loading blobs from disk.
outError	On failure, the error will be written here.

Returns

The blob data, or null on failure.

c4doc_getBySequence()

NODISCARD CBL_CORE_API C4Document * c4doc_getBySequence	(	C4Database *	database,
		C4SequenceNumber	,
		C4Error *	outError )

Gets a document from the database given its sequence number.

You must call c4doc_release() when finished with the document.

Note

The caller must use a lock for Database when this function is called.

c4doc_getDictBlobKey()

NODISCARD CBL_CORE_API bool c4doc_getDictBlobKey	(	FLDict	dict,
		C4BlobKey *	outKey )

Decodes the dict's "digest" property to a C4BlobKey.

Returns false if there is no such property or it's not a valid blob key.

Note

The caller must use a lock for Database when this function is called.

Assume dict is obtained from the database.

c4doc_getExpiration()

CBL_CORE_API C4Timestamp c4doc_getExpiration	(	C4Database *	db,
		C4String	docID,
		C4Error *	outError )

Returns the expiration time of a document, if one has been set, else 0.

Note

The caller must use a lock for Database when this function is called.

Parameters

db	The database to set the expiration date in
docID	The ID of the document to check
outError	Information about any error that occurred

Returns

The timestamp of the expiration date, in milliseconds since 1/1/1970, or 0 if the document does not expire, or -1 if an error occurred.

c4doc_getProperties()

CBL_CORE_API FLDict c4doc_getProperties

(

C4Document *

)

Returns the properties of the selected revision, i.e.

the root Fleece Dict.

Note

The caller must use a lock for Database when this function is called.

c4doc_getRemoteAncestor()

CBL_CORE_API C4SliceResult c4doc_getRemoteAncestor	(	C4Document *	doc,
		C4RemoteID	remoteDatabase )

Returns the revision ID that has been marked as current for the given remote database.

Note

The caller must use a lock for Database and Document when this function is called.

c4doc_getRevisionBody()

CBL_CORE_API C4Slice c4doc_getRevisionBody

(

C4Document *

doc

)

Returns the body (encoded Fleece data) of the selected revision, if available.

Note

The caller must use a lock for Document when this function is called.

Warning

In a version-vector document, and if this is not the current revision, the returned slice is invalidated the next time this function is called.

c4doc_getRevisionHistory()

CBL_CORE_API C4SliceResult c4doc_getRevisionHistory	(	C4Document *	doc,
		unsigned	maxRevs,
		const C4String	backToRevs[],
		unsigned	backToRevsCount )

Returns a string encoding the selected revision's history, as comma-separate revision/version IDs in reverse chronological order.

In a version-vector database this is of course the revision's version vector. It will be in global form (real SourceID instead of "*") unless the maxRevs parameter is 0.

Note

The caller must use a lock for Document when this function is called.

Parameters

doc	The document.
maxRevs	The maximum number of revisions to include in the result; or 0 for unlimited.
backToRevs	An array of revision IDs: the history should stop when it gets to any of these, and must go back to one of these if possible, even if it means skipping some revisions.
backToRevsCount	The number of revisions in the backToRevs array.

Returns

A string of comma-separate revision/version IDs in reverse chronological order.

c4doc_getSelectedRevIDGlobalForm()

CBL_CORE_API C4SliceResult c4doc_getSelectedRevIDGlobalForm

(

C4Document *

doc

)

Returns the selected revision's ID in a form that will make sense to another peer/server.

(This doesn't affect tree-based revIDs. In vector-based version IDs it uses the database's actual peer ID instead of the shorthand "*" character.)

Note

The caller must use a lock for Document when this function is called.

c4doc_hasOldMetaProperties()

CBL_CORE_API bool c4doc_hasOldMetaProperties

(

FLDict

doc

)

Returns true if the document contains 1.x metadata properties at top level.

Does NOT return true for "_attachments" because that property isn't obsolete.

Note

The caller must use a lock for Database when this function is called.

Assume doc is obtained from the database.

c4doc_hasRevisionBody()

CBL_CORE_API bool c4doc_hasRevisionBody

(

C4Document *

doc

)

Returns true if the body of the selected revision is available, i.e.

if c4doc_loadRevisionBody() would succeed.

Note

The caller must use a lock for Document when this function is called.

c4doc_isOldMetaProperty()

CBL_CORE_API bool c4doc_isOldMetaProperty

(

C4String

prop

)

Returns true if this is the name of a 1.x metadata property ("_id", "_rev", "_deleted".) Does NOT return true for "_attachments" because that property isn't obsolete.

c4doc_isRevRejected()

CBL_CORE_API bool c4doc_isRevRejected

(

C4Document *

doc

)

c4doc_loadRevisionBody()

NODISCARD CBL_CORE_API bool c4doc_loadRevisionBody	(	C4Document *	doc,
		C4Error *	outError )

Populates the body field of a doc's selected revision, if it was initially loaded without its body.

Note

The caller must use a lock for Document when this function is called.

c4doc_purgeRevision()

NODISCARD CBL_CORE_API int32_t c4doc_purgeRevision	(	C4Document *	doc,
		C4String	revID,
		C4Error *	outError )

Removes a branch from a document's history.

The revID must correspond to a leaf revision; that revision and its ancestors will be removed, except for ancestors that are shared with another branch. If the document has only one branch (no conflicts), or if the input revID is null, the purge will remove every revision, and saving the document will purge it (remove it completely from the database.) Must be called within a transaction. Remember to save the document afterwards.

Note

The caller must use a lock for Document when this function is called.

Parameters

doc	The document.
revID	The ID of the revision to purge. If null, all revisions are purged.
outError	Error information is stored here.

Returns

The total number of revisions purged (including ancestors), or -1 on error.

c4doc_put()

CBL_CORE_API C4Document * c4doc_put	(	C4Database *	database,
		const C4DocPutRequest *	request,
		size_t *	outCommonAncestorIndex,
		C4Error *	outError )

A high-level Put operation, to insert a new or downloaded revision.

If request->existingRevision is true, then request->history must contain the revision's history, with the revision's ID as the first item. Otherwise, a new revision will be created and assigned a revID. The parent revision ID, if any, should be given as the single item of request->history. Either way, on success the document is returned with the inserted revision selected. Note that actually saving the document back to the database is optional – it only happens if request->save is true. You can set this to false if you want to review the changes before saving, e.g. to run them through a validation function.

Note

The caller must use a lock for Database when this function is called.

c4doc_resolveConflict()

NODISCARD CBL_CORE_API bool c4doc_resolveConflict	(	C4Document *	doc,
		C4String	winningRevID,
		C4String	losingRevID,
		C4Slice	mergedBody,
		C4RevisionFlags	mergedFlags,
		C4Error *	error )

Resolves a conflict between two leaf revisions, by deleting one of them and optionally adding a new merged revision as a child of the other.

Must be called within a transaction. Remember to save the document afterwards.

Note

The caller must use a lock for Document when this function is called.

Parameters

doc	The document.
winningRevID	The conflicting revision to be kept (and optionally updated.)
losingRevID	The conflicting revision to be deleted.
mergedBody	The body of the merged revision, or NULL if none.
mergedFlags	Flags for the merged revision.
error	Error information is stored here.

Returns

True on success, false on failure.

c4doc_resolveConflict2()

NODISCARD CBL_CORE_API bool c4doc_resolveConflict2	(	C4Document *	doc,
		C4String	winningRevID,
		C4String	losingRevID,
		FLDict	mergedProperties,
		C4RevisionFlags	mergedFlags,
		C4Error *	error )

Resolves a conflict between two leaf revisions.

Identical to c4doc_resolveConflict except that it takes the merged body as a Fleece Dict, instead of pre-encoded Fleece data.

Note

The caller must use a lock for Document when this function is called.

c4doc_save()

NODISCARD CBL_CORE_API bool c4doc_save	(	C4Document *	doc,
		uint32_t	maxRevTreeDepth,
		C4Error *	outError )

Saves changes to a C4Document.

Must be called within a transaction. The revision history will be pruned to the maximum depth given.

Note

The caller must use a lock for Database and Document when this function is called.

c4doc_selectCommonAncestorRevision()

NODISCARD CBL_CORE_API bool c4doc_selectCommonAncestorRevision	(	C4Document *	doc,
		C4String	rev1ID,
		C4String	rev2ID )

Selects the common ancestor of two revisions.

Returns false if none is found.

Note

The caller must use a lock for Document when this function is called.

c4doc_selectCurrentRevision()

CBL_CORE_API bool c4doc_selectCurrentRevision

(

C4Document *

doc

)

Selects the current revision of a document.

(This is the first revision, in the order they appear in the document.)

Note

The caller must use a lock for Document when this function is called.

c4doc_selectNextLeafRevision()

NODISCARD CBL_CORE_API bool c4doc_selectNextLeafRevision	(	C4Document *	doc,
		bool	includeDeleted,
		bool	withBody,
		C4Error *	outError )

Selects the next leaf revision; like selectNextRevision but skips over non-leaves.

To distinguish between the end of the iteration and a failure, check the value of outError after the function returns false: if there's no error (code==0) it's normal.

Note

The caller must use a lock for Documnet when this function is called.

c4doc_selectNextRevision()

NODISCARD CBL_CORE_API bool c4doc_selectNextRevision

(

C4Document *

doc

)

Selects the next revision in priority order.

This can be used to iterate over all revisions, starting from the current revision.

Note

The caller must use a lock for Document when this function is called.

c4doc_selectParentRevision()

NODISCARD CBL_CORE_API bool c4doc_selectParentRevision

(

C4Document *

doc

)

Selects the parent of the selected revision, if it's known, else returns false.

Note

The caller must use a lock for Document when this function is called.

c4doc_selectRevision()

NODISCARD CBL_CORE_API bool c4doc_selectRevision	(	C4Document *	doc,
		C4String	revID,
		bool	withBody,
		C4Error *	outError )

Selects a specific revision of a document (or no revision, if revID is NULL.)

Note

The caller must use a lock for Document when this function is called.

c4doc_setExpiration()

CBL_CORE_API bool c4doc_setExpiration	(	C4Database *	db,
		C4String	docID,
		C4Timestamp	timestamp,
		C4Error *	outError )

Sets an expiration date on a document.

After this time the document will be purged from the database.

Note

The caller must use a lock for Database when this function is called.

Parameters

db	The database to set the expiration date in
docID	The ID of the document to set the expiration date for
timestamp	The timestamp of the expiration date, in milliseconds since 1/1/1970. A value of 0 indicates that the expiration should be cancelled.
outError	Information about any error that occurred

Returns

true on sucess, false on failure

c4doc_setRemoteAncestor()

NODISCARD CBL_CORE_API bool c4doc_setRemoteAncestor	(	C4Document *	doc,
		C4RemoteID	remoteDatabase,
		C4String	revID,
		C4Error *	error )

Marks a revision as current for the given remote database.

Note

The caller must use a lock for Database and Document when this function is called.

c4doc_update()

CBL_CORE_API C4Document * c4doc_update	(	C4Document *	doc,
		C4Slice	revisionBody,
		C4RevisionFlags	revisionFlags,
		C4Error *	error )

Adds a revision to a document already in memory as a C4Document.

This is more efficient than c4doc_put because it doesn't have to read from the database before writing; but if the C4Document doesn't have the current state of the document, it will fail with the error kC4ErrorConflict – then you'll need to get the current document and try again. The new revision is added as a child of the currently selected revision.

Note

The caller must use a lock for Database and Document when this function is called.

Parameters

doc	The document to update
revisionBody	The body of the new revision
revisionFlags	The flags of the new revision
error	Information about any error that occurred

Returns

On success, a new C4Document with the new revision selected; else NULL.

c4rev_equal()

CBL_CORE_API bool c4rev_equal	(	C4Slice	rev1,
		C4Slice	rev2 )

Returns true if two revision IDs are equivalent.

• Digest-based IDs are equivalent only if byte-for-byte equal.
• Version-vector based IDs are equivalent if their initial versions are equal.

c4rev_getGeneration()

CBL_CORE_API unsigned c4rev_getGeneration

(

C4String

revID

)

Given a tree-based revision ID, returns its generation number (the decimal number before the hyphen), or zero if it's unparseable.

Warning

This function does not support version-based revision IDs. Given one it returns zero, because the timestamp would be too big to return on platforms where unsigned is 32-bit. Use c4rev_getTimestamp to support version-based revIDs.

c4rev_getTimestamp()

CBL_CORE_API uint64_t c4rev_getTimestamp

(

C4String

revID

)

Given a revision ID that's a Version (of the form time@peer), returns its timestamp.

This can be interpreted as the time the revision was created, in nanoseconds since the Unix epoch, but it's not necessarily exact.

If this is a tree-based revision ID (of the form gen-digest), it returns the generation number. (This can be distinguished from a timestamp because it's much, much smaller! Timestamps will be at least 2^50, while generations rarely hit one million.)