An error value. These are returned by reference from API calls whose last parameter is a
C4Error*. The semantics are based on Cocoa’s usage of NSError:
A caller can pass NULL if it doesn’t care about the error.
The error is filled in only if the function fails, as indicated by its return value
(e.g. false or NULL.) If the function doesn’t fail, it does NOT zero out the error, so its
contents should be considered uninitialized garbage.
Client-defined metadata that can be associated with some objects like C4Database.
(See \ref c4db_setExtraInfo, \ref c4db_getExtraInfo.)
For example, if you have your own “Database” class, you could store a pointer to it in the
ExtraInfo of the corresponding C4Database so you can map from it back to your object.
Represents the current progress of a replicator.
The units fields should not be used directly, but divided (unitsCompleted/unitsTotal)
to give a very approximate progress fraction.
A query result enumerator.
Created by c4db_query. Must be freed with c4queryenum_release.
The fields of this struct represent the current matched index row, and are valid until the
next call to c4queryenum_next or c4queryenum_release.
A group of callbacks that define the implementation of sockets; the client must fill this
out and pass it to c4socket_registerFactory() before using any socket-based API.
These callbacks will be invoked on arbitrary background threads owned by LiteCore.
They should return quickly, and perform the operation asynchronously without blocking.
Opaque key for a dictionary. You are responsible for creating space for these; they can
go on the stack, on the heap, inside other objects, anywhere.
Be aware that the lookup operations that use these will write into the struct to store
“hints” that speed up future searches.
A heap-allocated block of memory returned from an API call.
The caller takes ownership, and must call \ref FLSliceResult_Release when done with it.
\warning The contents of the block must not be modified, since others may be using it.
\note This is equivalent to the C++ class alloc_slice. In C++ the easiest way to deal with
a FLSliceResult return value is to construct an alloc_slice from it, which will
adopt the reference, and release it in its destructor. For example:
alloc_slice foo( CopyFoo() );
A constant undefined value. This is not a NULL pointer, but its type is \ref kFLUndefined.
It can be stored in an \ref FLMutableArray or \ref FLMutableDict if you really, really
need to store an undefined/empty value, not just a JSON null.
Applies the JSON data created by CreateJSONDelta to the value old, which must be equal
to the old value originally passed to FLCreateJSONDelta, and returns a Fleece document
equal to the original nuu value.
@param old A value that’s typically the old/original state of some data. This must be
equal to the old value used when creating the jsonDelta.
@param jsonDelta A JSON-encoded delta created by FLCreateJSONDelta or FLEncodeJSONDelta.
@param outError On failure, error information will be stored where this points, if non-null.
@return The corresponding nuu value, encoded as Fleece, or null if an error occurred.
Returns JSON that encodes the changes to turn the value old into nuu.
(The format is documented in Fleece.md, but you should treat it as a black box.)
@param old A value that’s typically the old/original state of some data.
@param nuu A value that’s typically the new/changed state of the old data.
@return JSON data representing the changes from old to nuu, or NULL on
(extremely unlikely) failure.
Creates a FLDeepIterator to iterate over a dictionary.
Call FLDeepIterator_GetKey and FLDeepIterator_GetValue to get the first item,
then FLDeepIterator_Next.
Initializes a FLDictIterator struct to iterate over a dictionary.
Call FLDictIterator_GetKey and FLDictIterator_GetValue to get the first item,
then FLDictIterator_Next.
Cleans up after an iterator. Only needed if (a) the dictionary is a delta, and
(b) you stop iterating before the end (i.e. before FLDictIterator_Next returns false.)
Initializes an FLDictKey struct with a key string.
@warning The input string’s memory MUST remain valid for as long as the FLDictKey is in
use! (The FLDictKey stores a pointer to the string, but does not copy it.)
@param string The key string (UTF-8).
@return An initialized FLDictKey struct.
Looks up a key in a dictionary using an FLDictKey. If the key is found, “hint” data will
be stored inside the FLDictKey that will speed up subsequent lookups.
Creates an FLDoc from JSON-encoded data. The data is first encoded into Fleece, and the
Fleece data is kept by the doc; the input JSON data is no longer needed after this
function returns.
Creates an FLDoc from Fleece-encoded data that’s been returned as a result from
FLSlice_Copy or other API. The resulting document retains the data, so you don’t need to
worry about it remaining valid.
Returns the pointer associated with the document. You can use this together with
\ref FLValue_FindDoc to associate your own object with Fleece values, for instance to find
your object that “owns” a value:
myDoc = (app::Document*)FLDoc_GetAssociated(FLValue_FindDoc(val), "app::Document");.
@param doc The FLDoc to get a pointer from.
@param type The type of object expected, i.e. the same string literal passed to
\ref FLDoc_SetAssociated.
@return The associated pointer of that type, if any.
Associates an arbitrary pointer value with a document, and thus its contained values.
Allows client code to associate its own pointer with this FLDoc and its Values,
which can later be retrieved with \ref FLDoc_GetAssociated.
For example, this could be a pointer to an app::Document object, of which this Doc’s
root FLDict is its properties. You would store it by calling
FLDoc_SetAssociated(doc, myDoc, "app::Document");.
@param doc The FLDoc to store a pointer in.
@param pointer The pointer to store in the FLDoc.
@param type A C string literal identifying the type. This is used to avoid collisions
with unrelated code that might try to store a different type of value.
@return True if the pointer was stored, false if a pointer of a different type is
already stored.
@warning Be sure to clear this before the associated object is freed/invalidated!
@warning This function is not thread-safe. Do not concurrently get & set objects.
Applies the (parsed) JSON data created by CreateJSONDelta to the value old, which must be
equal to the old value originally passed to FLCreateJSONDelta, and writes the corresponding
nuu value to the encoder.
@param old A value that’s typically the old/original state of some data. This must be
equal to the old value used when creating the jsonDelta.
@param jsonDelta A JSON-encoded delta created by FLCreateJSONDelta or FLEncodeJSONDelta.
@param encoder A Fleece encoder to write the decoded nuu value to. (JSON encoding is not
supported.)
@return True on success, false on error; call FLEncoder_GetError for details.
Writes JSON that describes the changes to turn the value old into nuu.
(The format is documented in Fleece.md, but you should treat it as a black box.)
@param old A value that’s typically the old/original state of some data.
@param nuu A value that’s typically the new/changed state of the old data.
@param jsonEncoder An encoder to write the JSON to. Must have been created using
FLEncoder_NewWithOptions, with JSON or JSON5 format.
@return True on success, false on (extremely unlikely) failure.
Tells the encoder to logically append to the given Fleece document, rather than making a
standalone document. Any calls to FLEncoder_WriteValue() where the value points inside the
base data will write a pointer back to the original value.
The resulting data returned by FLEncoder_FinishDoc() will NOT be standalone; it can only
be used by first appending it to the base data.
@param e The FLEncoder affected.
@param base The base document to create an amendment of.
@param reuseStrings If true, then writing a string that already exists in the base will
just create a pointer back to the original. But the encoder has to scan the
base for strings first.
@param externPointers If true, pointers into the base will be marked with the extern
flag. This allows them to be resolved using the FLResolver_Begin function,
so that when the delta is used the base document can be anywhere in memory,
not just immediately preceding the delta document.
Begins writing an array value to an encoder. This pushes a new state where each
subsequent value written becomes an array item, until FLEncoder_EndArray is called.
@param reserveCount Number of array elements to reserve space for. If you know the size
of the array, providing it here speeds up encoding slightly. If you don’t know,
just use zero.
Begins writing a dictionary value to an encoder. This pushes a new state where each
subsequent key and value written are added to the dictionary, until FLEncoder_EndDict is
called.
Before adding each value, you must call FLEncoder_WriteKey (not FLEncoder_WriteString!),
to write the dictionary key.
@param reserveCount Number of dictionary items to reserve space for. If you know the size
of the dictionary, providing it here speeds up encoding slightly. If you don’t know,
just use zero.
Parses JSON data and writes the value(s) to the encoder as their Fleece equivalents.
(This acts as a single write, like WriteInt; it’s just that the value written is likely to
be an entire dictionary or array.)
Ends encoding; if there has been no error, it returns the encoded data, else null.
This does not free the FLEncoder; call FLEncoder_Free (or FLEncoder_Reset) next.
Ends encoding; if there has been no error, it returns the encoded Fleece data packaged in
an FLDoc. (This function does not support JSON encoding.)
This does not free the FLEncoder; call FLEncoder_Free (or FLEncoder_Reset) next.
Returns the byte offset in the encoded data where the next value will be written.
(Due to internal buffering, this is not the same as FLEncoder_BytesWritten.)
Returns an opaque reference to the last complete value written to the encoder, if possible.
Fails (returning 0) if nothing has been written, or if the value is inline and can’t be
referenced this way – that only happens with small scalars or empty collections.
Creates a new encoder, allowing some options to be customized.
@param format The output format to generate (Fleece, JSON, or JSON5.)
@param reserveSize The number of bytes to preallocate for the output. (Default is 256)
@param uniqueStrings (Fleece only) If true, string values that appear multiple times will be written
as a single shared value. This saves space but makes encoding slightly slower.
You should only turn this off if you know you’re going to be writing large numbers
of non-repeated strings. (Default is true)
Returns the data written so far as a standalone Fleece document, whose root is the last
value written. You can continue writing, and the final output returned by \ref FLEncoder_Finish will
consist of everything after this point. That second part can be used in the future by loading it
as an FLDoc with the first part as its extern reference.
Writes a binary data value (a blob) to an encoder. This can contain absolutely anything
including null bytes.
If the encoder is generating JSON, the blob will be written as a base64-encoded string.
Writes a timestamp to an encoder, as an ISO-8601 date string.
@note Since neither Fleece nor JSON have a ‘Date’ type, the encoded string has no
metadata that distinguishes it as a date. It’s just a string.)
@param encoder The encoder to write to.
@param ts The timestamp (milliseconds since Unix epoch 1-1-1970).
@param asUTC If true, date is written in UTC (GMT); if false, with the local timezone.
@return True on success, false on error.
Writes a 64-bit floating point number to an encoder.
@note As an implementation detail, the number may be encoded as a 32-bit float or even
as an integer, if this can be done without losing precision. For example, 123.0 will be
written as an integer, and 123.75 as a float.)
Writes a 32-bit floating point number to an encoder.
@note As an implementation detail, if the number has no fractional part and can be
represented exactly as an integer, it’ll be encoded as an integer to save space. This is
transparent to the reader, since if it requests the value as a float it’ll be returned
as floating-point.
Writes an integer to an encoder. The parameter is typed as int64_t but you can pass any
integral type (signed or unsigned) except for huge uint64_ts.
The number will be written in a compact form that uses only as many bytes as necessary.
Writes a null value to an encoder. (This is an explicitly-stored null, like the JSON
null, not the “undefined” value represented by a NULL FLValue pointer.)
Writes raw data directly to the encoded output.
(This is not the same as \ref FLEncoder_WriteData, which safely encodes a blob.)
@warning Do not call this unless you really know what you’re doing …
it’s quite unsafe, and only used for certain advanced purposes.
Writes a string to an encoder. The string must be UTF-8-encoded and must not contain any
zero bytes.
@warning Do not use this to write a dictionary key; use FLEncoder_WriteKey instead.
Writes an unsigned integer to an encoder.
@note This function is only really necessary for huge
64-bit integers greater than or equal to 2^63, which can’t be represented as int64_t.
Writes an undefined value to an encoder. (Its value when read will not be a NULL
pointer, but it can be recognized by FLValue_GetType returning kFLUndefined.)
@note The only real use for writing undefined values is to represent “holes” in an array.
An undefined dictionary value should be written simply by skipping the key and value.
Writes another reference (a “pointer”) to an already-written value, given a reference previously
returned from \ref FLEncoder_LastValueWritten. The effect is exactly the same as if you wrote the
entire value again, except that the size of the encoded data only grows by 4 bytes.
Converts valid JSON5 https://json5.org to JSON. Among other things, it converts single
quotes to double, adds missing quotes around dictionary keys, removes trailing commas,
and removes comments.
@note If given invalid JSON5, it will usually return an error, but may just ouput
comparably invalid JSON, in which case the caller’s subsequent JSON parsing will
detect the error. The types of errors it overlooks tend to be subtleties of string
or number encoding.
@param json5 The JSON5 to parse
@param outErrorMessage On failure, the error message will be stored here (if not NULL.)
As this is a \ref FLStringResult, you will be responsible for freeing it.
@param outErrorPos On a parse error, the byte offset in the input where the error occurred
will be stored here (if it’s not NULL.)
@param outError On failure, the error code will be stored here (if it’s not NULL.)
@return The converted JSON.
In a JSON encoder, adds a newline (‘\n’) and prepares to start encoding another
top-level object. The encoder MUST be not be within an array or dict.
Has no effect in a Fleece encoder.
Evaluates a key-path from a specifier string, for a given Fleece root object.
If you only need to evaluate the path once, this is a bit faster than creating an
FLKeyPath object, evaluating, then freeing it.
Appends a null value to the array and returns an \ref FLSlot that refers to that position.
You store a value to it by calling one of the nine FLSlot_Set... functions.
\warning You should immediately store a value into the FLSlot. Do not keep it around;
any changes to the array invalidate it.
Inserts a contiguous range of JSON null values into the array.
@param array The array to operate on.
@param firstIndex The zero-based index of the first value to be inserted.
@param count The number of items to insert.
Creates a new mutable Array from JSON. It is an error if the JSON is not an array.
Its initial ref-count is 1, so a call to FLMutableArray_Release will free it.
Removes contiguous items from the array.
@param array The array to operate on.
@param firstIndex The zero-based index of the first item to remove.
@param count The number of items to remove.
Returns an \ref FLSlot that refers to the given index of the given array.
You store a value to it by calling one of the nine FLSlot_Set... functions.
\warning You should immediately store a value into the FLSlot. Do not keep it around;
any changes to the array invalidate it.
Creates a new mutable Dict from json. It is an error if the JSON is not a dictionary/object.
Its initial ref-count is 1, so a call to FLMutableDict_Release will free it.
Returns an \ref FLSlot that refers to the given key/value pair of the given dictionary.
You store a value to it by calling one of the nine FLSlot_Set... functions.
\warning You should immediately store a value into the FLSlot. Do not keep it around;
any changes to the dictionary invalidate it.
Maps a key string to a number in the range [0…2047], or returns -1 if it isn’t mapped.
If the key doesn’t already have a mapping, and the add flag is true,
a new mapping is assigned and returned.
However, the add flag has no effect if the key is unmappable (is longer than 16 bytes
or contains non-identifier characters), or if all available integers have been assigned.
Copies a slice to a buffer, adding a trailing zero byte to make it a valid C string.
If there is not enough capacity the slice will be truncated, but the trailing zero byte is
always written.
@param s The FLSlice to copy.
@param buffer Where to copy the bytes. At least capacity bytes must be available.
@param capacity The maximum number of bytes to copy (including the trailing 0.)
@return True if the entire slice was copied, false if it was truncated.
Parses an ISO-8601 date-time string to a timestamp. On failure returns FLTimestampNone.
@note See also \ref FLValue_AsTimestamp, which takes an FLValue and interprets numeric
representations as well as strings.
Formats a timestamp as a date-time string in ISO-8601 format.
@note See also \ref FLEncoder_WriteDateString, which writes a timestamp to an FLEncoder.
@param timestamp A time, given as milliseconds since the Unix epoch (1/1/1970 00:00 UTC.)
@param asUTC If true, the timestamp will be given in universal time; if false, in the
local timezone.
@return A heap-allocated string, which you are responsible for releasing.
Returns a value coerced to a 32-bit floating point number.
True and false are returned as 1.0 and 0.0, and integers are converted to float. All other
types are returned as 0.0.
@warning Very large integers (outside approximately +/- 2^50) will lose precision due to
the limitations of IEEE 32-bit float format.
Returns a value coerced to a 32-bit floating point number.
True and false are returned as 1.0 and 0.0, and integers are converted to float. All other
types are returned as 0.0.
@warning Large integers (outside approximately +/- 2^23) will lose precision due to the
limitations of IEEE 32-bit float format.
Returns a value coerced to an integer. True and false are returned as 1 and 0, and
floating-point numbers are rounded. All other types are returned as 0.
@warning Large 64-bit unsigned integers (2^63 and above) will come out wrong. You can
check for these by calling FLValueIsUnsigned.
Returns a value coerced to an unsigned integer.
This is the same as FLValueAsInt except that it can’t handle negative numbers, but
does correctly return large uint64_t values of 2^63 and up.
Returns a pointer to the root value in the encoded data, or NULL if validation failed.
You should generally use an \ref FLDoc instead; it’s safer. Here’s why:
Returns true if the value is non-NULL and represents an integer >= 2^63. Such a value can’t
be represented in C as an int64_t, only a uint64_t, so you should access it by calling
FLValueAsUnsigned, not FLValueAsInt, which would return an incorrect (negative)
value.
Allocates a data/blob value on the heap. This is rarely needed – usually you’d just add data
to a mutable Array or Dict directly using one of their “…SetData or “…AppendData”
methods.
Allocates a string value on the heap. This is rarely needed – usually you’d just add a string
to a mutable Array or Dict directly using one of their “…SetString” or “…AppendString”
methods.
Decrements the ref-count of a mutable value, or of an immutable value’s \ref FLDoc.
If the ref-count reaches zero the corresponding object is freed.
@warning It is illegal to call this on a value obtained from \ref FLValue_FromData.
Increments the ref-count of a mutable value, or of an immutable value’s \ref FLDoc.
@warning It is illegal to call this on a value obtained from \ref FLValue_FromData.
Encodes a Fleece value as JSON5, a more lenient variant of JSON that allows dictionary
keys to be unquoted if they’re alphanumeric. This tends to be more readable.
@note Any Data values will be encoded as base64-encoded strings.
Most general Fleece to JSON converter.
@param v The Fleece value to encode
@param json5 If true, outputs JSON5, like \ref FLValue_ToJSON5
@param canonicalForm If true, outputs the JSON in a consistent “canonical” form. All
equivalent values should produce byte-for-byte identical canonical JSON.
This is useful for creating digital signatures, for example.
Returns a string representation of any scalar value. Data values are returned in raw form.
Arrays and dictionaries don’t have a representation and will return NULL.
Writes zeroes to size bytes of memory starting at dst.
Unlike a call to memset, these writes cannot be optimized away by the compiler.
This is useful for securely removing traces of passwords or encryption keys.
Associates an opaque “native handle” with this object. You can use this to store whatever
you need to represent the socket’s implementation, like a file descriptor.
Logs information about object in memory. Useful for debugging when \ref c4_getObjectCount
indicates there are leaks. (Note: In release builds this doesn’t have much to say, because
the instrumentation it needs is suppressed for performance purposes.)
A string describing the version of LiteCore. Currently this just describes the Git branch and
commit, in the form “Built from master branch, commit 0bc68f0d”.
Returns the number of objects that have been created but not yet freed.
This can be used as a debugging/testing tool to detect leaks; for example, capture the value
at the start of a test, then call again at the end and compare.
Schedules a function to be called asynchronously on a background thread.
@param task A pointer to the function to run. It must take a single void* argument and
return void. If it needs to return a value, it should call some other function you
define and pass that value as a parameter.
@param context An arbitrary pointer that will be passed to the function. You can use this
to provide state. Obviously, whatever this points to must remain valid until the
future time when task is called.
Wiring call for platforms without discoverable temporary directories. Simply sets the SQLite
temp directory so that it can write its temporary files without error. Several platforms need
to do this, but not all need to use this API.
@param path The path to a writable directory for temporary files for SQLite
@param err If an error happens (e.g. it is an error to call this function twice), this parameter
records it.
@note If you do call this function, you should call it before opening any databases.
@note Needless to say, the directory must already exist.
A simple URL parser that populates a C4Address from a URL string.
The fields of the address will point inside the url string.
@param url The URL to be parsed.
@param address On sucess, the fields of the struct this points to will be populated with
the address components. This that are slices will point into the
appropriate substrings of url.
@param dbName If non-NULL, then on success this slice will point to the last path
component of url; address->path will not include this component.
@return True on success, false on failure.
Stores a blob. The associated key will be written to outKey, if non-NULL.
If expectedKey is not NULL, then the operation will fail unless the contents actually
have that key.
Deletes the BlobStore’s blobs and directory, and (if successful) frees the object.
\warning This should only be used for unit testing. Never delete a BlobStore belonging to a
C4Database.
Closes/frees a BlobStore. (A NULL parameter is allowed.)
\warning This should only be used for unit testing. Never free a BlobStore belonging to a
C4Database.
Returns the path of the file that stores the blob, if possible. This call may fail with
error kC4ErrorWrongFormat if the blob is encrypted (in which case the file would be
unreadable by the caller) or with kC4ErrorUnsupported if for some implementation reason
the blob isn’t stored as a standalone file.
Thus, the caller MUST use this function only as an optimization, and fall back to reading
the contents via the API if it fails.
Also, it goes without saying that the caller MUST not modify the file!
Gets the content size of a blob given its key. Returns -1 if it doesn’t exist.
WARNING: If the blob is encrypted, the return value is a conservative estimate that may
be up to 16 bytes larger than the actual size.
Opens a BlobStore in a directory. If the flags allow creating, the directory will be
created if necessary.
Call c4blob_freeStore() when finished using the BlobStore.
\warning This should only be used for unit testing. Naked BlobStores are not supported.
@param dirPath The filesystem path of the directory holding the attachments.
@param flags Specifies options like create, read-only
@param encryptionKey Optional encryption algorithm & key
@param outError Error is returned here
@return The BlobStore reference, or NULL on error
Opens a write stream for creating a new blob. You should then call c4stream_write to
write the data, ending with c4stream_install to compute the blob’s key and add it to
the store, and then c4stream_closeWriter.
Returns the time range during which a (signed) certificate is valid.
@param cert The signed certificate.
@param outCreated On return, the date/time the cert became valid (was signed).
@param outExpires On return, the date/time at which the certificate expires.
Convenience function to create a new document. This just a wrapper around \ref c4coll_putDoc.
If the document already exists, it will fail with the error kC4ErrorConflict.
@note You must call \ref c4doc_release when finished with the document.
@param collection The collection to create the document in
@param docID Document ID to create; if null, a UUID will be generated
@param body Body of the document
@param revisionFlags The flags of the new revision
@param error Information about any error that occurred
@return On success, a new C4Document with the new revision selected; else NULL.
Creates a collection index, of the values of specific expressions across all documents.
The name is used to identify the index for later updating or deletion; if an index with the
same name already exists, it will be replaced unless it has the exact same expressions.
Deletes an index that was created by c4coll_createIndex.
@param collection The collection to index.
@param name The name of the index to delete
@param outError On failure, will be set to the error status.
@return True on success, false on failure.
Creates an enumerator ordered by docID.
Options have the same meanings as in Couchbase Lite.
There’s no ‘limit’ option; just stop enumerating when you’re done.
Caller is responsible for freeing the enumerator when finished with it.
@param collection The collection.
@param options Enumeration options (NULL for defaults).
@param outError Error will be stored here on failure.
@return A new enumerator, or NULL on failure.
Creates an enumerator ordered by sequence.
Caller is responsible for freeing the enumerator when finished with it.
@param collection The collection.
@param since The sequence number to start after. Pass 0 to start from the beginning.
@param options Enumeration options (NULL for defaults).
@param outError Error will be stored here on failure.
@return A new enumerator, or NULL on failure.
Gets a document from the collection given its ID.
The current revision is selected (if the document exists.)
@note You must call \ref c4doc_release when finished with the document.
@param collection The collection to read from.
@param docID The document’s ID.
@param 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.
@param content How much content to retrieve: metadata only, current revision, or all revisions.
@param outError On failure, error information is stored here.
@return A new C4Document instance (which must be released), or NULL.
Returns the expiration time of a document, if one has been set, else 0.
@param collection The collection to set the expiration date in
@param docID The ID of the document to check
@param outError Information about any error that occurred
@return 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.
Returns information about all indexes in the collection.
The result is a Fleece-encoded array of dictionaries, one per index.
Each dictionary has keys "name", "type" (a C4IndexType), and "expr" (the source expression).
@param collection The collection to check
@param outError On failure, will be set to the error status.
@return A Fleece-encoded array of dictionaries, or NULL on failure.
Moves a document to another collection, possibly with a different docID.
@param collection The document’s original collection.
@param docID The ID of the document to move.
@param toCollection The collection to move to.
@param newDocID The docID in the new collection, or a NULL slice to keep the original ID.
@param error Information about any error that occurred
@return True on success, false on failure.
Sets an expiration date on a document. After this time the
document will be purged from the database.
@param collection The collection to set the expiration date in
@param docID The ID of the document to set the expiration date for
@param timestamp The timestamp of the expiration date, in milliseconds since 1/1/1970.
A value of 0 indicates that the expiration should be cancelled.
@param outError Information about any error that occurred
@return true on sucess, false on failure
Returns the names of all existing collections in the given scope,
in the order in which they were created.
@note You are responsible for releasing the returned Fleece array.
Copies a prebuilt database from the given source path and places it in the destination
directory, with the given name. If a database already exists there, it will be overwritten.
However if there is a failure, the original database will be restored as if nothing
happened.
@param sourcePath The path to the database to be copied.
@param destinationName The name (without filename extension) of the database to create.
@param config Database configuration (including destination directory.)
@param error On failure, error info will be written here.
@return True on success, false on failure.
Creates and returns an empty collection with the given name & scope.
If the collection already exists, it just returns it.
If the scope doesn’t exist, it is implicitly created.
@note Be sure to read C4Collection Lifespan in c4Collection.h.
Creates a database index, of the values of specific expressions across all documents.
The name is used to identify the index for later updating or deletion; if an index with the
same name already exists, it will be replaced unless it has the exact same expressions.
@param database The database to index.
@param name The name of the index. Any existing index with the same name will be replaced,
unless it has the identical expressions (in which case this is a no-op.)
@param indexSpec The definition of the index in JSON or N1QL form. (See above.)
@param queryLanguage The query language (JSON or N1QL) of indexSpec is expressed.
@param indexType The type of index (value or full-text.)
@param indexOptions Options for the index. If NULL, each option will get a default value.
@param outError On failure, will be set to the error status.
@return True on success, false on failure.
Deletes the collection with the given name & scope.
Deleting the last collection from a scope implicitly deletes the scope.
@note It is legal to delete the default collection, but it cannot be re-created.
Deletes an index that was created by c4db_createIndex.
@param database The database to index.
@param name The name of the index to delete
@param outError On failure, will be set to the error status.
@return True on success, false on failure.
Deletes the file(s) for the database with the given name in the given directory.
All C4Databases at that path must be closed first or an error will result.
Returns false, with no error, if the database doesn’t exist.
Commits or aborts a transaction. If there have been multiple calls to beginTransaction, it
takes the same number of calls to endTransaction to actually end the transaction; only the
last one commits or aborts the database transaction.
Creates an enumerator ordered by docID.
Options have the same meanings as in Couchbase Lite.
There’s no ‘limit’ option; just stop enumerating when you’re done.
Caller is responsible for freeing the enumerator when finished with it.
@param database The database.
@param options Enumeration options (NULL for defaults).
@param outError Error will be stored here on failure.
@return A new enumerator, or NULL on failure.
Creates an enumerator ordered by sequence.
Caller is responsible for freeing the enumerator when finished with it.
@param database The database.
@param since The sequence number to start after. Pass 0 to start from the beginning.
@param options Enumeration options (NULL for defaults).
@param outError Error will be stored here on failure.
@return A new enumerator, or NULL on failure.
Returns the BlobStore associated with a bundled database.
Fails if the database is not bundled.
DO NOT call c4blob_freeStore on this! The C4Database will free it when it closes.
Returns the existing collection with the given name & scope, or NULL if it doesn’t exist.
@note Be sure to read C4Collection Lifespan in c4Collection.h.
Returns the default collection, whose name is “_default” (kC4DefaultCollectionName).
This is the one collection that exists in every newly created database.
When a pre-existing database is upgraded to support collections, all its documents are put
in the default collection.
@note Be sure to read C4Collection Lifespan in c4Collection.h.
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.
@param database The database to read from.
@param docID The document’s ID.
@param 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.
@param content How much content to retrieve: metadata only, current revision, or all revisions.
@param outError On failure, error information is stored here.
@return A new C4Document instance (which must be released), or NULL.
Returns information about all indexes in the database.
The result is a Fleece-encoded array of dictionaries, one per index.
Each dictionary has keys "name", "type" (a C4IndexType), and "expr" (the source expression).
@param database The database to check
@param outError On failure, will be set to the error status.
@return A Fleece-encoded array of dictionaries, or NULL on failure.
Given a remote database ID, returns its replication URL / unique identifier.
@param db The database.
@param remoteID The ID assigned to the remote database.
@return The URL/identifier, or a null slice if not found.
Looks up or creates a numeric ID identifying a remote database, for use with
c4doc_getRemoteAncestor() and c4doc_setRemoteAncestor().
@param db The database.
@param remoteAddress The replication URL of the remote db, or its other unique identifier.
@param canCreate If true, a new identifier will be created if one doesn’t exist.
@param outError Error information is stored here.
@return The ID, or 0 on error.
Purges all documents that have expired.
\warning This is generally unnecessary, since the background housekeeping task will do it.
You might want to call this if you require the purge to happen synchronously, just before
copying the database file or something like that.)
@return The number of documents purged, or -1 on error.
Takes the value of a “Set-Cookie:” header, received from the given host, from an HTTP
request with the given path, and saves the cookie into the database’s cookie store.
(Persistent cookies are saved as metadata in the database file until they expire.
Session cookies are kept in memory, until the last C4Database handle to the given database
is closed.)
Associates an arbitrary pointer with this database instance, for client use.
For example, this could be a reference to the higher-level object wrapping the database.
Creates a new collection observer, with a callback that will be invoked after one or more
documents in the collection have changed.
This is exactly like \ref c4dbobs_create, except that it acts on any collection.
@param collection The collection to observe.
@param callback The function to call after the collection changes.
@param context An arbitrary value that will be passed to the callback.
@return The new observer reference.
Identifies which documents have changed in the collection since the last time this function
was called, or since the observer was created. This function effectively “reads” changes
from a stream, in whatever quantity the caller desires. Once all of the changes have been
read, the observer is reset and ready to notify again.
Releases the memory used by the C4CollectionChange structs (to hold the docID and revID
strings.) This must be called after \ref c4dbobs_getChanges().
@param changes The same array of changes that was passed to \ref c4dbobs_getChanges.
@param numChanges The number of changes returned by \ref c4dbobs_getChanges, i.e. the number
of valid items in changes.
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.
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.
@param db The database to create the document in
@param docID Document ID to create; if null, a UUID will be generated
@param body Body of the document
@param revisionFlags The flags of the new revision
@param error Information about any error that occurred
@return On success, a new C4Document with the new revision selected; else NULL.
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.)
Generates a random 23-byte C string suitable for use as a unique new document ID.
@param buffer Where to write the string.
@param bufferSize Size of the buffer (must be at least kC4GeneratedIDLength + 1)
@return A pointer to the string in the buffer, or NULL if the buffer is too small.
Returns the contents of a blob dictionary, whether they’re inline in the “data” property,
or indirectly referenced via the “digest” property.
@note 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.)
@param dict A blob dictionary.
@param blobStore The database’s BlobStore, or NULL to suppress loading blobs from disk.
@param outError On failure, the error will be written here.
@return The blob data, or null on failure.
Returns the expiration time of a document, if one has been set, else 0.
@param db The database to set the expiration date in
@param docID The ID of the document to check
@param outError Information about any error that occurred
@return 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.
Returns the body (encoded Fleece data) of the selected revision, if available.
\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.
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 peerID instead of “*”) unless the maxRevs parameter is 0.
@param doc The document.
@param maxRevs The maximum number of revisions to include in the result; or 0 for unlimited.
@param 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.
@param backToRevsCount The number of revisions in the backToRevs array.
@return A string of comma-separate revision/version IDs in reverse chronological order.
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.)
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.
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.
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.
@param doc The document.
@param revID The ID of the revision to purge. If null, all revisions are purged.
@param outError Error information is stored here.
@return The total number of revisions purged (including ancestors), or -1 on error.
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.
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.
@param doc The document.
@param winningRevID The conflicting revision to be kept (and optionally updated.)
@param losingRevID The conflicting revision to be deleted.
@param mergedBody The body of the merged revision, or NULL if none.
@param mergedFlags Flags for the merged revision.
@param error Error information is stored here.
@return True on success, false on failure.
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.
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.
Sets an expiration date on a document. After this time the
document will be purged from the database.
@param db The database to set the expiration date in
@param docID The ID of the document to set the expiration date for
@param timestamp The timestamp of the expiration date, in milliseconds since 1/1/1970.
A value of 0 indicates that the expiration should be cancelled.
@param outError Information about any error that occurred
@return true on sucess, false on failure
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.
@param doc The document to update
@param revisionBody The body of the new revision
@param revisionFlags The flags of the new revision
@param error Information about any error that occurred
@return On success, a new C4Document with the new revision selected; else NULL.
Creates a new document observer, with a callback that will be invoked when the document
changes.
\note This is exactly like \ref c4docobs_create, except that it works on any collection.
@param collection The collection containing the document to observe.
@param docID The ID of the document to observe.
@param callback The function to call after the database changes.
@param context An arbitrary value that will be passed to the callback.
@return The new observer reference.
Closes an enumeration. This is optional, but can be used to free up resources if the
enumeration has not reached its end, but will not be freed for a while.
Returns the current document, if any, from an enumerator.
@param e The enumerator.
@param outError Error will be stored here on failure.
@return The document, or NULL if there is none or if an error occurred reading its body.
Caller is responsible for calling c4document_free when done with it.
Stores the metadata of the enumerator’s current document into the supplied
C4DocumentInfo struct. Unlike c4enum_getDocument(), this allocates no memory.
@param e The enumerator.
@param outInfo A pointer to a C4DocumentInfo struct that will be filled in if a document
is found.
@return True if the info was stored, false if there is no current document.
Advances the enumerator to the next document.
Returns false at the end, or on error; look at the C4Error to determine which occurred,
and don’t forget to free the enumerator.
Returns a description of an error, including the domain and code as well as the message.
The description is copied to the buffer as a C string.
It will not write past the end of the buffer; the message will be truncated if necessary.
@param error The error to describe
@param outBuffer Where to write the C string to
@param bufferSize The size of the buffer
@return A pointer to the string, i.e. to the first byte of the buffer.
Returns true if this error might go away when the network environment changes,
i.e. the client should retry after notification of a network status change.
Creates and stores a C4Error in *outError, if not NULL. Useful in functions that use the
LiteCore error reporting convention of taking a C4Error *outError parameter.
If set to true, then when a C4Error is created the current thread’s stack backtrace will
be captured along with it, and can later be examined by calling \ref c4error_getBacktrace.
Even if false, some errors (like assertion failures) will still have backtraces.
Stores a password into a C4EncryptionKey, by using the key-derivation algorithm PBKDF2
to securely convert the password into a raw binary key.
@param encryptionKey The raw key will be stored here.
@param password The password string.
@param alg The encryption algorithm to use. Must not be kC4EncryptionNone.
@return True on success, false on failure
Stores a password into a C4EncryptionKey, by using the key-derivation algorithm PBKDF2
to securely convert the password into a raw binary key. Uses SHA1 for the hashing function
as employed by PBKDF2.
@param encryptionKey The raw key will be stored here.
@param password The password string.
@param alg The encryption algorithm to use. Must not be kC4EncryptionNone.
@return True on success, false on failure
Returns the port number the listener is accepting connections on.
This is useful if you didn’t specify a port in the config (port=0), so you can find out which
port the kernel picked.
Returns the URL(s) of a database being shared, or of the root, separated by “\n” bytes.
The URLs will differ only in their hostname – there will be one for each IP address or known
hostname of the computer, or of the network interface.
Specifies a collection to be used in a P2P listener context. NOTE: A database
must have been previously shared under the same name, or this operation will fail.
@param listener The listener that should share the collection.
@param name The URI name to share it under, this must match the name of an already
shared DB.
@param collection The collection to share.
@param outError On failure, the error info is stored here if non-NULL.
Makes a database available from the network.
@param listener The listener that should share the database.
@param name The URI name to share it under, i.e. the path component in the URL.
If this is left null, a name will be chosen based as though you had called
\ref c4db_URINameFromPath.
@param db The database to share.
@param outError On failure, the error info is stored here if non-NULL.
@return True on success, false if the name is invalid as a URI component.
Logs a message/warning/error to a specific domain, if its current level is less than
or equal to the given level. This message will then be written to the current callback and/or
binary file, if their levels are less than or equal to the given level.
@param domain The domain to log to.
@param level The level of the message. If the domain’s level is greater than this,
nothing will be logged.
@param fmt printf-style format string, followed by arguments (if any).
Looks up a named log domain.
@param name The name of the domain, or NULL for the default domain.
@param create If true, the domain will be created if it doesn’t exist.
@return The domain object, or NULL if not found.
Changes the level of the given log domain.
This setting is global to the entire process.
Logging is further limited by the levels assigned to the current callback and/or binary file.
For example, if you set the Foo domain’s level to Verbose, and the current log callback is
at level Warning while the binary file is at Verbose, then verbose Foo log messages will be
written to the file but not to the callback.
If set to true, LiteCore will log a warning of the form “LiteCore throwing %s error %d: %s”
just before throwing an internal exception. This can be a good way to catch the source where
an error occurs.
Returns true if logging to this domain at this level will have an effect.
This is called by the C4Log macros (below), to skip the possibly-expensive evaluation of
parameters if nothing will be logged anyway.
(This is not the same as comparing c4log_getLevel, because even if the domain’s level
indicates it would log, logging could still be suppressed by the global callbackLevel or
binaryFileLevel.)
Causes log messages to be written to a file, overwriting any previous contents.
The data is written in an efficient and compact binary form that can be read using the
“litecorelog” tool.
@param options The options to use when setting up the binary logger
@param error On failure, the filesystem error that caused the call to fail.
@return True on success, false on failure.
Registers (or unregisters) a log callback, and sets the minimum log level to report.
Before this is called, a default callback is used that writes to stderr at the Info level.
NOTE: this setting is global to the entire process.
@param level The minimum level of message to log.
@param callback The logging callback, or NULL to disable logging entirely.
@param preformatted If true, log messages will be formatted before invoking the callback,
so the fmt parameter will be the actual string to log, and the args parameter
will be NULL.
Returns a suggested title for a column, which may be:
An alias specified in an ‘AS’ modifier in the column definition
A property name
A function/operator that computes the column value, e.g. ‘MAX()’ or ‘+’
Each column’s title is unique. If multiple columns would have the same title, the
later ones (in numeric order) will have “ #2“, “#3”, etc. appended.
Returns a string describing the implementation of the compiled query.
This is intended to be read by a developer for purposes of optimizing the query, especially
to add database indexes.
Given a C4FullTextMatch from the enumerator, returns the entire text of the property that
was matched. (The result depends only on the term’s dataSource and property fields,
so if you get multiple matches of the same property in the same document, you can skip
redundant calls with the same values.)
To find the actual word that was matched, use the term’s start and length fields
to get a substring of the returned (UTF-8) string.
Compiles a query from an expression given as JSON.
The expression is a predicate that describes which documents should be returned.
A separate, optional sort expression describes the ordering of the results.
@param database The database to be queried.
@param language The language (syntax) of the query expression.
@param expression The query expression, either JSON or N1QL.
@param outErrorPos If non-NULL, then on a parse error the approximate byte offset in the
input expression will be stored here (or -1 if not known/applicable.)
@param error Error will be written here if the function fails.
@result A new C4Query, or NULL on failure.
Runs a compiled query.
NOTE: Queries will run much faster if the appropriate properties are indexed.
Indexes must be created explicitly by calling c4db_createIndex.
@param query The compiled query to run.
@param options Query options; currently unused, just pass NULL.
@param encodedParameters Options parameter values; if this parameter is not NULL,
it overrides the parameters assigned by \ref c4query_setParameters.
@param outError On failure, will be set to the error status.
@return An enumerator for reading the rows, or NULL on error.
Sets the parameter values to use when running the query, if no parameters are given to
\ref c4query_run.
@param query The compiled query to run.
@param encodedParameters JSON- or Fleece-encoded dictionary whose keys correspond
to the named parameters in the query expression, and values correspond to the
values to bind. Any unbound parameters will be null.
Closes an enumerator without freeing it. This is optional, but can be used to free up
resources if the enumeration has not reached its end, but will not be freed for a while.
Returns the total number of rows in the query, if known.
Not all query enumerators may support this (but the current implementation does.)
@param e The query enumerator
@param outError On failure, an error will be stored here (probably kC4ErrorUnsupported.)
@return The number of rows, or -1 on failure.
Jumps to a specific row. Not all query enumerators may support this (but the current
implementation does.)
@param e The query enumerator
@param rowIndex The number of the row, starting at 0, or -1 to restart before first row
@param outError On failure, an error will be stored here (probably kC4ErrorUnsupported.)
@return True on success, false on failure.
Creates a new query observer, with a callback that will be invoked when the query
results change, with an enumerator containing the new results.
\note The callback isn’t invoked immediately after a change, and won’t be invoked after
every change, to avoid performance problems. Instead, there’s a brief delay so multiple
changes can be coalesced.
\note The new observer needs to be enabled by calling \ref c4queryobs_setEnabled.
Returns the current query results, if any.
When the observer is created, the results are initially NULL until the query finishes
running in the background.
Once the observer callback is called, the results are available.
\note You are responsible for releasing the returned reference.
@param obs The query observer.
@param forget If true, the observer will not hold onto the enumerator, and subsequent calls
will return NULL until the next time the observer notifies you. This can help
conserve memory, since the query result data will be freed as soon as you
release the enumerator.
@param error If the last evaluation of the query failed, the error will be stored here.
@return The current query results, or NULL if the query hasn’t run or has failed.
Reads a raw document from the database. In Couchbase Lite the store named “info” is used
for per-database key/value pairs, and the store “_local” is used for local documents.
Frees a replicator reference.
Does not stop the replicator – if the replicator still has other internal references,
it will keep going. If you need the replicator to stop, call \ref c4repl_stop first.
\note This function is thread-safe.
Gets a fleece encoded list of IDs of documents who have revisions pending push. This
API is a snapshot and results may change between the time the call was made and the time
the call returns.
Checks if the document with the given ID has revisions pending push. This
API is a snapshot and results may change between the time the call was made and the time
the call returns.
Creates a new networked replicator.
@param db The local database.
@param remoteAddress The address of the remote server.
@param remoteDatabaseName The name of the database at the remote address.
@param params Replication parameters (see above.)
@param outError Error, if replication can’t be created.
@return The newly created replicator, or NULL on error.
Creates a new replicator from an already-open C4Socket. This is for use by listeners
that accept incoming connections, wrap them by calling c4socket_fromNative(), then
start a passive replication to service them.
@param db The local database.
@param openSocket An already-created C4Socket.
@param params Replication parameters. Will usually use kC4Passive modes.
@param outError Error, if replication can’t be created.
@return The newly created replicator, or NULL on error.
Tells a replicator that’s in the offline state to reconnect immediately.
\note This function is thread-safe.
@param repl The replicator.
@param outError On failure, error information is stored here.
@return True if the replicator will reconnect, false if it won’t.
Informs the replicator whether it’s considered possible to reach the remote host with
the current network configuration. The default value is true. This only affects the
replicator’s behavior while it’s in the Offline state:
Setting it to false will cancel any pending retry and prevent future automatic retries.
Setting it back to true will initiate an immediate retry.
\note This function is thread-safe.
Puts the replicator in or out of “suspended” state.
Setting suspended=true causes the replicator to disconnect and enter Offline state;
it will not attempt to reconnect while it’s suspended.
Setting suspended=false causes the replicator to attempt to reconnect, if it was
connected when suspended, and is still in Offline state.
\note This function is thread-safe.
Tells a replicator to start. Ignored if it’s not in the Stopped state.
\note This function is thread-safe.
@param repl The C4Replicator instance.
@param reset If true, the replicator will reset its checkpoint and start replication from the beginning
Notifies LiteCore that the peer has requested to close the socket using the WebSocket protocol.
(Should only be called by sockets whose factory’s framing equals to kC4NoFraming.)
LiteCore will call the factory’s requestClose callback in response when it’s ready to
acknowledge the close.
@param socket The socket.
@param status The WebSocket status sent by the peer, typically 1000.
@param message An optional human-readable message sent by the peer.
Notifies LiteCore that a C4SocketFactory.write request has been completed, i.e. the bytes
have been written to the socket.
@param socket The socket.
@param byteCount The number of bytes that were written.
Constructs a C4Socket from a “native handle”, whose interpretation is up to the
C4SocketFactory. This is used by listeners to handle an incoming replication connection.
@warning You MUST immediately call c4socket_retain on this pointer (and the usual
c4socket_release when done.) This is inconsistent with the general ref-counting
convention, but fixing this function to return a retained value would cause all
existing platforms to leak C4Sockets, so we’re leaving it alone.
@param factory The C4SocketFactory that will manage the socket.
@param nativeHandle A value known to the factory that represents the underlying socket,
such as a file descriptor or a native object pointer.
@param address The address of the remote peer making the connection.
@return A new C4Socket initialized with the nativeHandle.
Notification that a socket has received an HTTP response, with the given headers (encoded
as a Fleece dictionary.) This should be called just before c4socket_opened or
c4socket_closed.
@param socket The socket being opened.
@param httpStatus The HTTP/WebSocket status code from the peer; expected to be 200 if the
connection is successful, else an HTTP status >= 300 or WebSocket status >= 1000.
@param responseHeadersFleece The HTTP response headers, encoded as a Fleece dictionary
whose keys are the header names (with normalized case) and values are header values
as strings.
Notifies LiteCore that data was received from the socket. If the factory’s
framing equals to kC4NoFraming, the data must be a single complete message; otherwise it’s
raw bytes that will be un-framed by LiteCore.
LiteCore will acknowledge when it’s received and processed the data, by calling
C4SocketFactory.completedReceive. For flow-control purposes, the client should keep track
of the number of unacknowledged bytes, and stop reading from the underlying stream if that
grows too large.
@param socket The socket.
@param data The data received, either a message or raw bytes.
One-time registration of default socket callbacks. If used, must be called before using any socket-based
API including the replicator. Do not call multiple times.
Closes a blob write-stream. If c4stream_install was not already called (or was called but
failed), the temporary file will be deleted without adding the blob to the store.
(A NULL parameter is allowed, and is a no-op.)
Computes the blob-key (digest) of the data written to the stream. This should only be
called after writing the entire data. No more data can be written after this call.
Adds the data written to the stream as a finished blob to the store.
If expectedKey is not NULL, then the operation will fail unless the contents actually
have that key. (If you don’t know ahead of time what the key should be, call
c4stream_computeBlobKey beforehand to derive it, and pass NULL for expectedKey.)
This function does not close the writer.
Reads from an open stream.
@param stream The open stream to read from
@param buffer Where to copy the read data to
@param maxBytesToRead The maximum number of bytes to read to the buffer
@param error Error is returned here
@return The actual number of bytes read, or 0 if an error occurred
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.
@param context The same value given in the C4DocPutRequest’s deltaCBContext field.
@param doc The document; its selected revision is the one requested in the deltaSourceRevID.
@param delta The contents of the request’s body or allocedBody.
@param revFlags If not nullptr, its value may be updated after the delta is applied.
@param outError If the callback fails, store an error here if it’s non-NULL.
@return The body to store in the new revision, or a null slice on failure.
Callback invoked by a document observer.
@param observer The observer that initiated the callback.
@param docID The ID of the document that changed.
@param sequence The sequence number of the change.
@param context user-defined parameter given when registering the callback.
Called when a client connects, during the TLS handshake, if a client certificate is received.
@param listener The C4Listener handling the connection.
@param clientCertData The client’s X.509 certificate in DER encoding.
@param context The tlsCallbackContext from the C4TLSConfig.
@return True to allow the connection, false to refuse it.
Called when a client connects, after the TLS handshake (if any), when the initial HTTP request is
received.
@param listener The C4Listener handling the connection.
@param authHeader The “Authorization” header value from the client’s HTTP request, or null.
@param context The callbackContext from the listener config.
@return True to allow the connection, false to refuse it.
Callback invoked by a query observer, notifying that the query results have changed.
The actual enumerator is not passed to the callback, but can be retrieved by calling
\ref c4queryobs_getEnumerator.
@warning This function is called on a random background thread! Be careful of thread
safety. Do not spend too long in this callback or other observers may be delayed.
It’s best to do nothing except schedule a call on your preferred thread/queue.
@param observer The observer triggering the callback.
@param query The C4Query that the observer belongs to.
@param context The context parameter you passed to \ref c4queryobs_create.
Callback a client can register, to hear about the replication status of documents.
By default, only errors will be reported via this callback.
To also receive callbacks for successfully completed documents, set the
kC4ReplicatorOptionProgressLevel option to a value greater than zero.
Callback that can choose to reject an incoming pulled revision, or stop a local
revision from being pushed, by returning false.
(Note: In the case of an incoming revision, no flags other than ‘deletion’ and
‘hasAttachments’ will be set.)
A heap-allocated block of memory returned from an API call.
The caller takes ownership, and must call \ref FLSliceResult_Release when done with it.
\warning The contents of the block must not be modified, since others may be using it.
\note This is equivalent to the C++ class alloc_slice. In C++ the easiest way to deal with
a FLSliceResult return value is to construct an alloc_slice from it, which will
adopt the reference, and release it in its destructor. For example:
alloc_slice foo( CopyFoo() );
A heap-allocated block of memory returned from an API call.
The caller takes ownership, and must call \ref FLSliceResult_Release when done with it.
\warning The contents of the block must not be modified, since others may be using it.
\note This is equivalent to the C++ class alloc_slice. In C++ the easiest way to deal with
a FLSliceResult return value is to construct an alloc_slice from it, which will
adopt the reference, and release it in its destructor. For example:
alloc_slice foo( CopyFoo() );
A date/time representation used for document expiration (and in date/time queries.)
Measured in milliseconds since the Unix epoch (1/1/1970, midnight UTC.)
A value of 0 represents “no expiration”.
A heap-allocated block of memory returned from an API call.
The caller takes ownership, and must call \ref FLSliceResult_Release when done with it.
\warning The contents of the block must not be modified, since others may be using it.
\note This is equivalent to the C++ class alloc_slice. In C++ the easiest way to deal with
a FLSliceResult return value is to construct an alloc_slice from it, which will
adopt the reference, and release it in its destructor. For example:
alloc_slice foo( CopyFoo() );