LiteCore
Couchbase Lite cross-platform core implementation
|
Data Structures | |
struct | C4EncryptionKey |
Encryption key specified in a C4DatabaseConfig. More... | |
struct | C4DatabaseConfig2 |
Main database configuration struct (version 2) for use with c4db_openNamed etc. More... | |
struct | C4UUID |
struct | C4CollectionSpec |
Full identifier of a collection in a database, including its scope. More... | |
Configuration | |
enum | C4DatabaseFlags : uint32_t { kC4DB_Create = 0x01 , kC4DB_ReadOnly = 0x02 , kC4DB_AutoCompact = 0x04 , kC4DB_VersionVectors = 0x08 , kC4DB_NoUpgrade = 0x20 , kC4DB_NonObservable = 0x40 , kC4DB_FakeVectorClock = 0x80 } |
enum | C4EncryptionAlgorithm : uint32_t { kC4EncryptionNone = 0 , kC4EncryptionAES256 } |
enum | C4EncryptionKeySize : uint64_t { kC4EncryptionKeySizeAES256 = 32 } |
CBL_CORE_API const char *const | kC4DatabaseFilenameExtension |
Filename extension of databases – ".cblite2". | |
Database Maintenance | |
enum | C4MaintenanceType : uint32_t { kC4Compact , kC4Reindex , kC4IntegrityCheck , kC4QuickOptimize , kC4FullOptimize } |
Configuration | |
NODISCARD CBL_CORE_API bool | c4key_setPassword (C4EncryptionKey *encryptionKey, C4String password, C4EncryptionAlgorithm alg) |
Stores a password into a C4EncryptionKey, by using the key-derivation algorithm PBKDF2 to securely convert the password into a raw binary key. | |
NODISCARD CBL_CORE_API bool | c4key_setPasswordSHA1 (C4EncryptionKey *encryptionKey, C4String password, C4EncryptionAlgorithm alg) |
Stores a password into a C4EncryptionKey, by using the key-derivation algorithm PBKDF2 to securely convert the password into a raw binary key. | |
CBL_CORE_API void | c4_setExtensionPath (C4String path) |
CBL_CORE_API bool | c4_enableExtension (C4String name, C4String extensionPath, C4Error *outError) |
Asks LiteCore to look for and validate the presence of an extension given the name of the extension and the path in which it is supposed to reside. | |
Lifecycle | |
CBL_CORE_API bool | c4db_exists (C4String name, C4String inDirectory) |
Returns true if a database with the given name exists in the directory. | |
NODISCARD CBL_CORE_API C4Database * | c4db_openNamed (C4String name, const C4DatabaseConfig2 *config, C4Error *outError) |
Opens a database given its name (without the ".cblite2" extension) and directory. | |
NODISCARD CBL_CORE_API C4Database * | c4db_openAgain (C4Database *db, C4Error *outError) |
Opens a new handle to the same database file as db . | |
NODISCARD CBL_CORE_API bool | c4db_copyNamed (C4String sourcePath, C4String destinationName, const C4DatabaseConfig2 *config, C4Error *error) |
Copies a prebuilt database from the given source path and places it in the destination directory, with the given name. | |
NODISCARD CBL_CORE_API bool | c4db_close (C4Database *database, C4Error *outError) |
Closes the database. | |
NODISCARD CBL_CORE_API bool | c4db_delete (C4Database *database, C4Error *outError) |
Closes the database and deletes the file/bundle. | |
NODISCARD CBL_CORE_API bool | c4db_deleteNamed (C4String dbName, C4String inDirectory, C4Error *outError) |
Deletes the file(s) for the database with the given name in the given directory. | |
NODISCARD CBL_CORE_API bool | c4db_rekey (C4Database *database, const C4EncryptionKey *newKey, C4Error *outError) |
Changes a database's encryption key (removing encryption if it's NULL.) | |
NODISCARD CBL_CORE_API bool | c4_shutdown (C4Error *outError) |
Closes down the storage engines. | |
Accessors | |
CBL_CORE_API C4String | c4db_getName (C4Database *) |
Returns the name of the database, as given to c4db_openNamed . | |
CBL_CORE_API C4StringResult | c4db_getPath (C4Database *) |
Returns the path of the database. | |
CBL_CORE_API const C4DatabaseConfig2 * | c4db_getConfig2 (C4Database *database) |
Returns the configuration the database was opened with. | |
CBL_CORE_API uint64_t | c4db_getDocumentCount (C4Database *database) |
Returns the number of (undeleted) documents in the database. | |
CBL_CORE_API C4SequenceNumber | c4db_getLastSequence (C4Database *database) |
Returns the latest sequence number allocated to a revision. | |
CBL_CORE_API C4Timestamp | c4db_nextDocExpiration (C4Database *database) |
Returns the timestamp at which the next document expiration should take place, or 0 if there are no documents with expiration times. | |
NODISCARD CBL_CORE_API int64_t | c4db_purgeExpiredDocs (C4Database *db, C4Error *) |
Purges all documents that have expired. | |
NODISCARD CBL_CORE_API bool | c4db_getUUIDs (C4Database *database, C4UUID *publicUUID, C4UUID *privateUUID, C4Error *outError) |
Returns the database's public and/or private UUIDs. | |
CBL_CORE_API void | c4db_setExtraInfo (C4Database *database, C4ExtraInfo) |
Associates an arbitrary pointer with this database instance, for client use. | |
CBL_CORE_API C4ExtraInfo | c4db_getExtraInfo (C4Database *database) |
Returns the C4ExtraInfo associated with this db reference. | |
Database Maintenance | |
NODISCARD CBL_CORE_API bool | c4db_maintenance (C4Database *database, C4MaintenanceType type, C4Error *outError) |
Performs database maintenance. | |
Transactions | |
NODISCARD CBL_CORE_API bool | c4db_beginTransaction (C4Database *database, C4Error *outError) |
Begins a transaction. | |
NODISCARD CBL_CORE_API bool | c4db_endTransaction (C4Database *database, bool commit, C4Error *outError) |
Commits or aborts a transaction. | |
CBL_CORE_API bool | c4db_isInTransaction (C4Database *database) |
Is a transaction active? | |
Scopes and Collections | |
#define | kC4DefaultScopeID FLSTR("_default") |
#define | kC4DefaultCollectionName FLSTR("_default") |
#define | kC4DefaultCollectionSpec ((C4CollectionSpec){kC4DefaultCollectionName, kC4DefaultScopeID}) |
#define kC4DefaultCollectionName FLSTR("_default") |
#define kC4DefaultCollectionSpec ((C4CollectionSpec){kC4DefaultCollectionName, kC4DefaultScopeID}) |
#define kC4DefaultScopeID FLSTR("_default") |
enum C4DatabaseFlags : uint32_t |
enum C4EncryptionAlgorithm : uint32_t |
enum C4EncryptionKeySize : uint64_t |
enum C4MaintenanceType : uint32_t |
Enumerator | |
---|---|
kC4Compact | Shrinks the database file by removing any empty pages, and deletes blobs that are no longer referenced by any documents. (Runs SQLite |
kC4Reindex | Rebuilds indexes from scratch. Normally never needed, but can be used to help diagnose/troubleshoot cases of database corruption if only indexes are affected. (Runs SQLite |
kC4IntegrityCheck | Checks for database corruption, as might be caused by a damaged filesystem, or memory corruption. (Runs SQLite |
kC4QuickOptimize | Quickly updates database statistics that may help optimize queries that have been run by this Database since it was opened. The more queries that have been run, the more effective this will be, but it tries to do its work quickly by scanning only portions of indexes. This operation is also performed automatically by c4db_close. (Runs SQLite |
kC4FullOptimize | Fully scans all indexes to gather database statistics that help optimize queries. This may take some time, depending on the size of the indexes, but it doesn't have to be redone unless the database changes drastically, or new indexes are created. (Runs SQLite |
CBL_CORE_API bool c4_enableExtension | ( | C4String | name, |
C4String | extensionPath, | ||
C4Error * | outError ) |
Asks LiteCore to look for and validate the presence of an extension given the name of the extension and the path in which it is supposed to reside.
It makes an attempt to only check things that have the possibility of being corrected by the user (i.e. if there is a bug in the extension and it cannot load functionally that won't be caught)
name | The name of the extension (corresponds to the filename without the extension or "lib" prefix) |
extensionPath | The path in which the extension should be found |
outError | On failure, will store the error. |
CBL_CORE_API void c4_setExtensionPath | ( | C4String | path | ) |
NODISCARD CBL_CORE_API bool c4_shutdown | ( | C4Error * | outError | ) |
Closes down the storage engines.
Must close all databases first. You don't generally need to do this, but it can be useful in tests.
NODISCARD CBL_CORE_API bool c4db_beginTransaction | ( | C4Database * | database, |
C4Error * | outError ) |
Begins a transaction.
Transactions can nest; only the first call actually creates a database transaction.
NODISCARD CBL_CORE_API bool c4db_close | ( | C4Database * | database, |
C4Error * | outError ) |
Closes the database.
Does not free the handle, although any operation other than c4db_release() will fail with an error.
NODISCARD CBL_CORE_API bool c4db_copyNamed | ( | C4String | sourcePath, |
C4String | destinationName, | ||
const C4DatabaseConfig2 * | config, | ||
C4Error * | error ) |
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.
sourcePath | The path to the database to be copied. |
destinationName | The name (without filename extension) of the database to create. |
config | Database configuration (including destination directory.) |
error | On failure, error info will be written here. |
NODISCARD CBL_CORE_API bool c4db_delete | ( | C4Database * | database, |
C4Error * | outError ) |
Closes the database and deletes the file/bundle.
Does not free the handle, although any operation other than c4db_release() will fail with an error. All C4Databases at that path must be closed first or an error will result.
NODISCARD CBL_CORE_API bool c4db_deleteNamed | ( | C4String | dbName, |
C4String | inDirectory, | ||
C4Error * | outError ) |
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.
NODISCARD CBL_CORE_API bool c4db_endTransaction | ( | C4Database * | database, |
bool | commit, | ||
C4Error * | outError ) |
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.
CBL_CORE_API bool c4db_exists | ( | C4String | name, |
C4String | inDirectory ) |
Returns true if a database with the given name exists in the directory.
CBL_CORE_API const C4DatabaseConfig2 * c4db_getConfig2 | ( | C4Database * | database | ) |
Returns the configuration the database was opened with.
CBL_CORE_API uint64_t c4db_getDocumentCount | ( | C4Database * | database | ) |
Returns the number of (undeleted) documents in the database.
CBL_CORE_API C4ExtraInfo c4db_getExtraInfo | ( | C4Database * | database | ) |
Returns the C4ExtraInfo associated with this db reference.
CBL_CORE_API C4SequenceNumber c4db_getLastSequence | ( | C4Database * | database | ) |
Returns the latest sequence number allocated to a revision.
CBL_CORE_API C4String c4db_getName | ( | C4Database * | ) |
Returns the name of the database, as given to c4db_openNamed
.
This is the filename without the ".cblite2" extension.
CBL_CORE_API C4StringResult c4db_getPath | ( | C4Database * | ) |
Returns the path of the database.
NODISCARD CBL_CORE_API bool c4db_getUUIDs | ( | C4Database * | database, |
C4UUID * | publicUUID, | ||
C4UUID * | privateUUID, | ||
C4Error * | outError ) |
Returns the database's public and/or private UUIDs.
(Pass NULL for ones you don't want.)
CBL_CORE_API bool c4db_isInTransaction | ( | C4Database * | database | ) |
Is a transaction active?
NODISCARD CBL_CORE_API bool c4db_maintenance | ( | C4Database * | database, |
C4MaintenanceType | type, | ||
C4Error * | outError ) |
Performs database maintenance.
For more detail, see the descriptions of the C4MaintenanceType enum constants.
CBL_CORE_API C4Timestamp c4db_nextDocExpiration | ( | C4Database * | database | ) |
Returns the timestamp at which the next document expiration should take place, or 0 if there are no documents with expiration times.
NODISCARD CBL_CORE_API C4Database * c4db_openAgain | ( | C4Database * | db, |
C4Error * | outError ) |
Opens a new handle to the same database file as db
.
The new connection is completely independent and can be used on another thread.
NODISCARD CBL_CORE_API C4Database * c4db_openNamed | ( | C4String | name, |
const C4DatabaseConfig2 * | config, | ||
C4Error * | outError ) |
Opens a database given its name (without the ".cblite2" extension) and directory.
NODISCARD CBL_CORE_API int64_t c4db_purgeExpiredDocs | ( | C4Database * | db, |
C4Error * | ) |
Purges all documents that have expired.
NODISCARD CBL_CORE_API bool c4db_rekey | ( | C4Database * | database, |
const C4EncryptionKey * | newKey, | ||
C4Error * | outError ) |
Changes a database's encryption key (removing encryption if it's NULL.)
CBL_CORE_API void c4db_setExtraInfo | ( | C4Database * | database, |
C4ExtraInfo | ) |
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.
The destructor
field of the C4ExtraInfo
can be used to provide a function that will be called when the C4Database is freed, so it can free any resources associated with the pointer.
NODISCARD CBL_CORE_API bool c4key_setPassword | ( | C4EncryptionKey * | encryptionKey, |
C4String | password, | ||
C4EncryptionAlgorithm | alg ) |
Stores a password into a C4EncryptionKey, by using the key-derivation algorithm PBKDF2 to securely convert the password into a raw binary key.
encryptionKey | The raw key will be stored here. |
password | The password string. |
alg | The encryption algorithm to use. Must not be kC4EncryptionNone. |
NODISCARD CBL_CORE_API bool c4key_setPasswordSHA1 | ( | C4EncryptionKey * | encryptionKey, |
C4String | password, | ||
C4EncryptionAlgorithm | alg ) |
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.
encryptionKey | The raw key will be stored here. |
password | The password string. |
alg | The encryption algorithm to use. Must not be kC4EncryptionNone. |
|
extern |
Filename extension of databases – ".cblite2".
Includes the period.