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
`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 |

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

@ -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)`
| 参数 | 描述 |