diff --git a/docs/api.md b/docs/api.md index 9f8fbf0..5aef64a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -31,13 +31,13 @@ Through the API of KVDB and TSDB, the blob object can be returned, and the stora ### Initialize KVDB -`fdb_err_t fdb_kvdb_init(fdb_kvdb_t db, const char *name, const char *part_name, struct fdb_default_kv *default_kv, void *user_data)` +`fdb_err_t fdb_kvdb_init(fdb_kvdb_t db, const char *name, const char *path, struct fdb_default_kv *default_kv, void *user_data)` | Parameters | Description | | ---------- | -------------------------------------- ------------------ | | db | Database Objects | | name | Database name | -| part_name | Which partition in the FAL partition table to use | +| path | FAL mode: the partition name in the partition table, file mode: the path where the database is saved | | default_kv | The default KV collection, when the first initialization, the default KV will be written to the database | | user_data | User-defined data, NULL if not available | | Back | Error Code | @@ -58,10 +58,13 @@ Through the command control word, the user can perform some control operations o The supported command control words are as follows: ```C -#define FDB_KVDB_CTRL_SET_SEC_SIZE 0x0 /**< Set sector size */ -#define FDB_KVDB_CTRL_GET_SEC_SIZE 0x1 /**< Get sector size */ -#define FDB_KVDB_CTRL_SET_LOCK 0x2 /**< Set lock function */ -#define FDB_KVDB_CTRL_SET_UNLOCK 0x3 /**< Set unlock function */ +#define FDB_KVDB_CTRL_SET_SEC_SIZE 0x00 /**< set sector size control command, this change MUST before database initialization */ +#define FDB_KVDB_CTRL_GET_SEC_SIZE 0x01 /**< get sector size control command */ +#define FDB_KVDB_CTRL_SET_LOCK 0x02 /**< set lock function control command */ +#define FDB_KVDB_CTRL_SET_UNLOCK 0x03 /**< set unlock function control command */ +#define FDB_KVDB_CTRL_SET_FILE_MODE 0x09 /**< set file mode control command, this change MUST before database initialization */ +#define FDB_KVDB_CTRL_SET_MAX_SIZE 0x0A /**< set database max size in file mode control command, this change MUST before database initialization */ +#define FDB_KVDB_CTRL_SET_NOT_FORMAT 0x0B /**< set database NOT format mode control command, this change MUST before database initialization */ ``` #### Sector size and block size @@ -70,13 +73,24 @@ The internal storage structure of FlashDB is composed of N sectors, and each for By default, KVDB will use 1 times the block size as the sector size, that is, 4096. At this time, the KVDB cannot store a KV longer than 4096. If you want to save, for example, a KV with a length of 10K, you can use the control function to set the sector size to 12K or larger. +### Deinitialize KVDB + +`fdb_err_t fdb_kvdb_deinit(fdb_kvdb_t db)` + +| Parameters | Description | +| ---------- | ---------------- | +| db | Database Objects | + ### Set KV This method can be used to increase and modify KV. - **Add**: When there is no KV with this name in KVDB, the new operation will be performed; + - **Modify**: The KV name in the input parameter exists in the current KVDB, then the KV value is modified to the value in the input parameter; + > In the internal implementation of KVDB, modifying KV will delete the old KV first, and then add a new KV, so the remaining capacity of the database will become smaller after the modification + Get the corresponding value by KV's name. Support two interfaces #### Set blob type KV @@ -166,6 +180,8 @@ Unlike the `fdb_kv_get_blob` API, this API does not execute the reading of value ### Delete KV +> In the internal implementation of KVDB, deleting KV will not be completely removed from KVDB, but marked for deletion, so the remaining capacity of the database will not change after deletion. + `fdb_err_t fdb_kv_del(fdb_kvdb_t db, const char *key)` | Parameters | Description | @@ -176,7 +192,7 @@ Unlike the `fdb_kv_get_blob` API, this API does not execute the reading of value ### Reset KVDB -Reset the KV in KVDB to the initial default value +Reset the KV in KVDB to the **first initial** default value `fdb_err_t fdb_kv_set_default(fdb_kvdb_t db)` @@ -226,13 +242,13 @@ Using this iterator API, all KVs in the entire KVDB can be traversed. ### Initialize TSDB -`fdb_err_t fdb_tsdb_init(fdb_tsdb_t db, const char *name, const char *part_name, fdb_get_time get_time, size_t max_len, void *user_data)` +`fdb_err_t fdb_tsdb_init(fdb_tsdb_t db, const char *name, const char *path, fdb_get_time get_time, size_t max_len, void *user_data)` | Parameters | Description | | --------- | ------------------------------- | | db | Database Objects | | name | Database name | -| part_name | Which partition in the FAL partition table to use | +| path | FAL mode: the partition name in the partition table, file mode: the path where the database is saved | | get_time | Function to get the current timestamp | | max_len | Maximum length of each TSL | | user_data | User-defined data, NULL if not available | @@ -254,15 +270,26 @@ Through the command control word, the user can perform some control operations o The supported command control words are as follows: ```C -#define FDB_TSDB_CTRL_SET_SEC_SIZE 0x0 /**< Set sector size */ -#define FDB_TSDB_CTRL_GET_SEC_SIZE 0x1 /**< Get sector size */ -#define FDB_TSDB_CTRL_SET_LOCK 0x2 /**< Set lock function */ -#define FDB_TSDB_CTRL_SET_UNLOCK 0x3 /**< Set unlock function */ -#define FDB_TSDB_CTRL_SET_ROLLOVER 0x4 /**< Set whether to roll writing, default roll. When setting non-rolling, if the database is full, no more writes can be appended */ -#define FDB_TSDB_CTRL_GET_ROLLOVER 0x5 /**< Get whether to scroll to write */ -#define FDB_TSDB_CTRL_GET_LAST_TIME 0x6 /**< Get the timestamp when TSL was last appended */ +#define FDB_TSDB_CTRL_SET_SEC_SIZE 0x00 /**< set sector size control command, this change MUST before database initialization */ +#define FDB_TSDB_CTRL_GET_SEC_SIZE 0x01 /**< get sector size control command */ +#define FDB_TSDB_CTRL_SET_LOCK 0x02 /**< set lock function control command */ +#define FDB_TSDB_CTRL_SET_UNLOCK 0x03 /**< set unlock function control command */ +#define FDB_TSDB_CTRL_SET_ROLLOVER 0x04 /**< set rollover control command, this change MUST before database initialization */ +#define FDB_TSDB_CTRL_GET_ROLLOVER 0x05 /**< get rollover control command */ +#define FDB_TSDB_CTRL_GET_LAST_TIME 0x06 /**< get last save time control command */ +#define FDB_TSDB_CTRL_SET_FILE_MODE 0x09 /**< set file mode control command, this change MUST before database initialization */ +#define FDB_TSDB_CTRL_SET_MAX_SIZE 0x0A /**< set database max size in file mode control command, this change MUST before database initialization */ +#define FDB_TSDB_CTRL_SET_NOT_FORMAT 0x0B /**< set database NOT formatable mode control command, this change MUST before database initialization */ ``` +### Deinitialize TSDB + +`fdb_err_t fdb_tsdb_deinit(fdb_tsdb_t db)` + +| Parameters | Description | +| ---------- | ---------------- | +| db | Database Objects | + ### Append TSL For TSDB, the process of adding TSL is the process of appending a new TSL to the end of TSDB @@ -318,6 +345,8 @@ According to the incoming time period, query the number of TSLs that meet the st ### Set TSL status +For TSL status, please refer to `enum fdb_tsl_status`. TSL status MUST be set in order. [click to view sample](sample-tsdb-basic.md) + `fdb_err_t fdb_tsl_set_status(fdb_tsdb_t db, fdb_tsl_t tsl, fdb_tsl_status_t status)` | Parameters | Description | diff --git a/docs/zh-cn/api.md b/docs/zh-cn/api.md index cc03478..133a7fc 100644 --- a/docs/zh-cn/api.md +++ b/docs/zh-cn/api.md @@ -31,13 +31,13 @@ ### 初始化 KVDB -`fdb_err_t fdb_kvdb_init(fdb_kvdb_t db, const char *name, const char *part_name, struct fdb_default_kv *default_kv, void *user_data)` +`fdb_err_t fdb_kvdb_init(fdb_kvdb_t db, const char *name, const char *path, struct fdb_default_kv *default_kv, void *user_data)` | 参数 | 描述 | | ---------- | -------------------------------------------------------- | | db | 数据库对象 | | name | 数据库名称 | -| part_name | 使用 FAL 分区表中的哪一个分区 | +| path | FAL 模式：分区表中的分区名，文件模式：数据库保存的路径 | | default_kv | 默认 KV 集合，第一次初始化时，将会把默认 KV 写入数据库中 | | user_data | 用户自定义数据，没有时传入 NULL | | 返回 | 错误码 | @@ -58,10 +58,13 @@ 支持的命令控制字如下： ```C -#define FDB_KVDB_CTRL_SET_SEC_SIZE 0x0 /**< 设置扇区大小 */ -#define FDB_KVDB_CTRL_GET_SEC_SIZE 0x1 /**< 获取扇区大小 */ -#define FDB_KVDB_CTRL_SET_LOCK 0x2 /**< 设置加锁函数 */ -#define FDB_KVDB_CTRL_SET_UNLOCK 0x3 /**< 设置解锁函数 */ +#define FDB_KVDB_CTRL_SET_SEC_SIZE 0x00 /**< 设置扇区大小，需要在数据库初始化前配置 */ +#define FDB_KVDB_CTRL_GET_SEC_SIZE 0x01 /**< 获取扇区大小 */ +#define FDB_KVDB_CTRL_SET_LOCK 0x02 /**< 设置加锁函数 */ +#define FDB_KVDB_CTRL_SET_UNLOCK 0x03 /**< 设置解锁函数 */ +#define FDB_KVDB_CTRL_SET_FILE_MODE 0x09 /**< 设置文件模式，需要在数据库初始化前配置 */ +#define FDB_KVDB_CTRL_SET_MAX_SIZE 0x0A /**< 在文件模式下，设置数据库最大大小，需要在数据库初始化前配置 */ +#define FDB_KVDB_CTRL_SET_NOT_FORMAT 0x0B /**< 设置初始化时不进行格式化，需要在数据库初始化前配置 */ ``` #### 扇区大小与块大小 @@ -70,13 +73,24 @@ FlashDB 内部存储结构由 N 个扇区组成，每次格式化时是以扇区 默认 KVDB 会使用 1倍 的块大小作为扇区大小，即：4096。此时，该 KVDB 无法存入超过 4096 长度的 KV 。如果想要存入比如：10K 长度的 KV ，可以通过 control 函数，设置扇区大小为 12K，或者更大大小即可。 +### 反初始化 KVDB + +`fdb_err_t fdb_kvdb_deinit(fdb_kvdb_t db)` + +| 参数 | 描述 | +| ---- | ---------- | +| db | 数据库对象 | + ### 设置 KV 使用此方法可以实现对 KV 的增加和修改功能。 - **增加** ：当 KVDB 中不存在该名称的 KV 时，则会执行新增操作； + - **修改** ：入参中的 KV 名称在当前 KVDB 中存在，则把该 KV 值修改为入参中的值； + > 在 KVDB 内部实现中，修改 KV 会先删除旧的 KV ，再增加新的 KV，所以修改后数据库剩余容量会变小 + 通过 KV 的名字来获取其对应的值。支持两种接口 #### 设置 blob 类型KV @@ -166,6 +180,8 @@ if (blob.saved.len > 0) { ### 删除 KV +> 在 KVDB 内部实现中，删除 KV 并不会完全从 KVDB 中移除，而是标记为了删除状态，所以删除后数据库剩余容量不会有变化 + `fdb_err_t fdb_kv_del(fdb_kvdb_t db, const char *key)` | 参数 | 描述 | @@ -176,7 +192,7 @@ if (blob.saved.len > 0) { ### 重置 KVDB -将 KVDB 中的 KV 重置为初始时的默认值 +将 KVDB 中的 KV 重置为 **首次初始时** 的默认值 `fdb_err_t fdb_kv_set_default(fdb_kvdb_t db)` @@ -226,17 +242,17 @@ if (blob.saved.len > 0) { ### 初始化 TSDB -`fdb_err_t fdb_tsdb_init(fdb_tsdb_t db, const char *name, const char *part_name, fdb_get_time get_time, size_t max_len, void *user_data)` +`fdb_err_t fdb_tsdb_init(fdb_tsdb_t db, const char *name, const char *path, fdb_get_time get_time, size_t max_len, void *user_data)` -| 参数 | 描述 | -| --------- | ------------------------------- | -| db | 数据库对象 | -| name | 数据库名称 | -| part_name | 使用 FAL 分区表中的哪一个分区 | -| get_time | 获取当前时间戳的函数 | -| max_len | 每条 TSL 的最大长度 | -| user_data | 用户自定义数据，没有时传入 NULL | -| 返回 | 错误码 | +| 参数 | 描述 | +| --------- | ------------------------------------------------------ | +| db | 数据库对象 | +| name | 数据库名称 | +| path | FAL 模式：分区表中的分区名，文件模式：数据库保存的路径 | +| get_time | 获取当前时间戳的函数 | +| max_len | 每条 TSL 的最大长度 | +| user_data | 用户自定义数据，没有时传入 NULL | +| 返回 | 错误码 | ### 控制 TSDB @@ -254,15 +270,26 @@ if (blob.saved.len > 0) { 支持的命令控制字如下： ```C -#define FDB_TSDB_CTRL_SET_SEC_SIZE 0x0 /**< 设置扇区大小 */ -#define FDB_TSDB_CTRL_GET_SEC_SIZE 0x1 /**< 获取扇区大小 */ -#define FDB_TSDB_CTRL_SET_LOCK 0x2 /**< 设置加锁函数 */ -#define FDB_TSDB_CTRL_SET_UNLOCK 0x3 /**< 设置解锁函数 */ -#define FDB_TSDB_CTRL_SET_ROLLOVER 0x4 /**< 设置是否滚动写入，默认滚动。设置非滚动时，如果数据库写满，无法再追加写入 */ -#define FDB_TSDB_CTRL_GET_ROLLOVER 0x5 /**< 获取是否滚动写入 */ -#define FDB_TSDB_CTRL_GET_LAST_TIME 0x6 /**< 获取上次追加 TSL 时的时间戳 */ +#define FDB_TSDB_CTRL_SET_SEC_SIZE 0x00 /**< 设置扇区大小，需要在数据库初始化前配置 */ +#define FDB_TSDB_CTRL_GET_SEC_SIZE 0x01 /**< 获取扇区大小 */ +#define FDB_TSDB_CTRL_SET_LOCK 0x02 /**< 设置加锁函数 */ +#define FDB_TSDB_CTRL_SET_UNLOCK 0x03 /**< 设置解锁函数 */ +#define FDB_TSDB_CTRL_SET_ROLLOVER 0x04 /**< 设置是否滚动写入，默认滚动。设置非滚动时，如果数据库写满，无法再追加写入。需要在数据库初始化前配置 */ +#define FDB_TSDB_CTRL_GET_ROLLOVER 0x05 /**< 获取是否滚动写入 */ +#define FDB_TSDB_CTRL_GET_LAST_TIME 0x06 /**< 获取上次追加 TSL 时的时间戳 */ +#define FDB_TSDB_CTRL_SET_FILE_MODE 0x09 /**< 设置文件模式，需要在数据库初始化前配置，需要在数据库初始化前配置 */ +#define FDB_TSDB_CTRL_SET_MAX_SIZE 0x0A /**< 在文件模式下，设置数据库最大大小，需要在数据库初始化前配置 */ +#define FDB_TSDB_CTRL_SET_NOT_FORMAT 0x0B /**< 设置初始化时不进行格式化，需要在数据库初始化前配置 */ ``` +### 反初始化 TSDB + +`fdb_err_t fdb_tsdb_deinit(fdb_tsdb_t db)` + +| 参数 | 描述 | +| ---- | ---------- | +| db | 数据库对象 | + ### 追加 TSL 对于 TSDB ，新增 TSL 的过程，就是往 TSDB 末尾追加新 TSL 的过程 @@ -318,6 +345,8 @@ if (blob.saved.len > 0) { ### 设置 TSL 状态 +TSL 状态详见 `enum fdb_tsl_status` ，必须按照顺序设置 TSL 状态， [点击查看示例](zh-cn/sample-tsdb-basic.md) + `fdb_err_t fdb_tsl_set_status(fdb_tsdb_t db, fdb_tsl_t tsl, fdb_tsl_status_t status)` | 参数 | 描述 |