libs
/
FlashDB
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[doc] Update the docs to latest.

This commit is contained in:
armink 2021-10-02 12:00:15 +08:00
parent c9cfd4598c
commit f3b3e61804
2 changed files with 98 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/api.md
View File

@ -31,13 +31,13 @@ Through the API of KVDB and TSDB, the blob object can be returned, and the stora
### Initialize KVDB ### 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 | | Parameters | Description |
| ---------- | -------------------------------------- ------------------ | | ---------- | -------------------------------------- ------------------ |
| db | Database Objects | | db | Database Objects |
| name | Database name | | 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 | | 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 | | user_data | User-defined data, NULL if not available |
| Back | Error Code | | 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: The supported command control words are as follows:
```C ```C
#define FDB_KVDB_CTRL_SET_SEC_SIZE 0x0 /**< Set sector size */ #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 0x1 /**< Get sector size */ #define FDB_KVDB_CTRL_GET_SEC_SIZE 0x01 /**< get sector size control command */
#define FDB_KVDB_CTRL_SET_LOCK 0x2 /**< Set lock function */ #define FDB_KVDB_CTRL_SET_LOCK 0x02 /**< set lock function control command */
#define FDB_KVDB_CTRL_SET_UNLOCK 0x3 /**< Set unlock function */ #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 #### 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. 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 ### Set KV
This method can be used to increase and modify 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; - **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; - **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 Get the corresponding value by KV's name. Support two interfaces
#### Set blob type KV #### 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 ### 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)` `fdb_err_t fdb_kv_del(fdb_kvdb_t db, const char *key)`
| Parameters | Description | | 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 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)` `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 ### 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 | | Parameters | Description |
| --------- | ------------------------------- | | --------- | ------------------------------- |
| db | Database Objects | | db | Database Objects |
| name | Database name | | 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 | | get_time | Function to get the current timestamp |
| max_len | Maximum length of each TSL | | max_len | Maximum length of each TSL |
| user_data | User-defined data, NULL if not available | | 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: The supported command control words are as follows:
```C ```C
#define FDB_TSDB_CTRL_SET_SEC_SIZE 0x0 /**< Set sector size */ #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 0x1 /**< Get sector size */ #define FDB_TSDB_CTRL_GET_SEC_SIZE 0x01 /**< get sector size control command */
#define FDB_TSDB_CTRL_SET_LOCK 0x2 /**< Set lock function */ #define FDB_TSDB_CTRL_SET_LOCK 0x02 /**< set lock function control command */
#define FDB_TSDB_CTRL_SET_UNLOCK 0x3 /**< Set unlock function */ #define FDB_TSDB_CTRL_SET_UNLOCK 0x03 /**< set unlock function control command */
#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_SET_ROLLOVER 0x04 /**< set rollover control command, this change MUST before database initialization */
#define FDB_TSDB_CTRL_GET_ROLLOVER 0x5 /**< Get whether to scroll to write */ #define FDB_TSDB_CTRL_GET_ROLLOVER 0x05 /**< get rollover control command */
#define FDB_TSDB_CTRL_GET_LAST_TIME 0x6 /**< Get the timestamp when TSL was last appended */ #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 ### Append TSL
For TSDB, the process of adding TSL is the process of appending a new TSL to the end of TSDB 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 ### 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)` `fdb_err_t fdb_tsl_set_status(fdb_tsdb_t db, fdb_tsl_t tsl, fdb_tsl_status_t status)`
| Parameters | Description | | Parameters | Description |

77
docs/zh-cn/api.md
View File

@ -31,13 +31,13 @@
### 初始化 KVDB ### 初始化 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 | 数据库对象 | | db | 数据库对象 |
| name | 数据库名称 | | name | 数据库名称 |
| part_name | 使用 FAL 分区表中的哪一个分区 | | path | FAL 模式：分区表中的分区名，文件模式：数据库保存的路径 |
| default_kv | 默认 KV 集合，第一次初始化时，将会把默认 KV 写入数据库中 | | default_kv | 默认 KV 集合，第一次初始化时，将会把默认 KV 写入数据库中 |
| user_data | 用户自定义数据，没有时传入 NULL | | user_data | 用户自定义数据，没有时传入 NULL |
| 返回 | 错误码 | | 返回 | 错误码 |
@ -58,10 +58,13 @@
支持的命令控制字如下： 支持的命令控制字如下：
```C ```C
#define FDB_KVDB_CTRL_SET_SEC_SIZE 0x0 /**< 设置扇区大小 */ #define FDB_KVDB_CTRL_SET_SEC_SIZE 0x00 /**< 设置扇区大小，需要在数据库初始化前配置 */
#define FDB_KVDB_CTRL_GET_SEC_SIZE 0x1 /**< 获取扇区大小 */ #define FDB_KVDB_CTRL_GET_SEC_SIZE 0x01 /**< 获取扇区大小 */
#define FDB_KVDB_CTRL_SET_LOCK 0x2 /**< 设置加锁函数 */ #define FDB_KVDB_CTRL_SET_LOCK 0x02 /**< 设置加锁函数 */
#define FDB_KVDB_CTRL_SET_UNLOCK 0x3 /**< 设置解锁函数 */ #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 会使用 1倍 的块大小作为扇区大小，即：4096。此时，该 KVDB 无法存入超过 4096 长度的 KV 。如果想要存入比如：10K 长度的 KV ，可以通过 control 函数，设置扇区大小为 12K，或者更大大小即可。
### 反初始化 KVDB
`fdb_err_t fdb_kvdb_deinit(fdb_kvdb_t db)`
| 参数 | 描述 |
| ---- | ---------- |
| db | 数据库对象 |
### 设置 KV ### 设置 KV
使用此方法可以实现对 KV 的增加和修改功能。 使用此方法可以实现对 KV 的增加和修改功能。
- **增加** ：当 KVDB 中不存在该名称的 KV 时，则会执行新增操作； - **增加** ：当 KVDB 中不存在该名称的 KV 时，则会执行新增操作；
- **修改** ：入参中的 KV 名称在当前 KVDB 中存在，则把该 KV 值修改为入参中的值； - **修改** ：入参中的 KV 名称在当前 KVDB 中存在，则把该 KV 值修改为入参中的值；
> 在 KVDB 内部实现中，修改 KV 会先删除旧的 KV ，再增加新的 KV，所以修改后数据库剩余容量会变小
通过 KV 的名字来获取其对应的值。支持两种接口 通过 KV 的名字来获取其对应的值。支持两种接口
#### 设置 blob 类型KV #### 设置 blob 类型KV
@ -166,6 +180,8 @@ if (blob.saved.len > 0) {
### 删除 KV ### 删除 KV
> 在 KVDB 内部实现中，删除 KV 并不会完全从 KVDB 中移除，而是标记为了删除状态，所以删除后数据库剩余容量不会有变化
`fdb_err_t fdb_kv_del(fdb_kvdb_t db, const char *key)` `fdb_err_t fdb_kv_del(fdb_kvdb_t db, const char *key)`
| 参数 | 描述 | | 参数 | 描述 |
@ -176,7 +192,7 @@ if (blob.saved.len > 0) {
### 重置 KVDB ### 重置 KVDB
将 KVDB 中的 KV 重置为初始时的默认值 将 KVDB 中的 KV 重置为 **首次初始时** 的默认值
`fdb_err_t fdb_kv_set_default(fdb_kvdb_t db)` `fdb_err_t fdb_kv_set_default(fdb_kvdb_t db)`
@ -226,17 +242,17 @@ if (blob.saved.len > 0) {
### 初始化 TSDB ### 初始化 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 | 数据库对象 | | db | 数据库对象 |
| name | 数据库名称 | | name | 数据库名称 |
| part_name | 使用 FAL 分区表中的哪一个分区 | | path | FAL 模式：分区表中的分区名，文件模式：数据库保存的路径 |
| get_time | 获取当前时间戳的函数 | | get_time | 获取当前时间戳的函数 |
| max_len | 每条 TSL 的最大长度 | | max_len | 每条 TSL 的最大长度 |
| user_data | 用户自定义数据，没有时传入 NULL | | user_data | 用户自定义数据，没有时传入 NULL |
| 返回 | 错误码 | | 返回 | 错误码 |
### 控制 TSDB ### 控制 TSDB
@ -254,15 +270,26 @@ if (blob.saved.len > 0) {
支持的命令控制字如下： 支持的命令控制字如下：
```C ```C
#define FDB_TSDB_CTRL_SET_SEC_SIZE 0x0 /**< 设置扇区大小 */ #define FDB_TSDB_CTRL_SET_SEC_SIZE 0x00 /**< 设置扇区大小，需要在数据库初始化前配置 */
#define FDB_TSDB_CTRL_GET_SEC_SIZE 0x1 /**< 获取扇区大小 */ #define FDB_TSDB_CTRL_GET_SEC_SIZE 0x01 /**< 获取扇区大小 */
#define FDB_TSDB_CTRL_SET_LOCK 0x2 /**< 设置加锁函数 */ #define FDB_TSDB_CTRL_SET_LOCK 0x02 /**< 设置加锁函数 */
#define FDB_TSDB_CTRL_SET_UNLOCK 0x3 /**< 设置解锁函数 */ #define FDB_TSDB_CTRL_SET_UNLOCK 0x03 /**< 设置解锁函数 */
#define FDB_TSDB_CTRL_SET_ROLLOVER 0x4 /**< 设置是否滚动写入，默认滚动。设置非滚动时，如果数据库写满，无法再追加写入 */ #define FDB_TSDB_CTRL_SET_ROLLOVER 0x04 /**< 设置是否滚动写入，默认滚动。设置非滚动时，如果数据库写满，无法再追加写入。需要在数据库初始化前配置 */
#define FDB_TSDB_CTRL_GET_ROLLOVER 0x5 /**< 获取是否滚动写入 */ #define FDB_TSDB_CTRL_GET_ROLLOVER 0x05 /**< 获取是否滚动写入 */
#define FDB_TSDB_CTRL_GET_LAST_TIME 0x6 /**< 获取上次追加 TSL 时的时间戳 */ #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 ### 追加 TSL
对于 TSDB ，新增 TSL 的过程，就是往 TSDB 末尾追加新 TSL 的过程 对于 TSDB ，新增 TSL 的过程，就是往 TSDB 末尾追加新 TSL 的过程
@ -318,6 +345,8 @@ if (blob.saved.len > 0) {
### 设置 TSL 状态 ### 设置 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)` `fdb_err_t fdb_tsl_set_status(fdb_tsdb_t db, fdb_tsl_t tsl, fdb_tsl_status_t status)`
| 参数 | 描述 | | 参数 | 描述 |