Struct TSDB 

pub struct TSDB<S: NorFlash> { /* private fields */ }

Implementations

impl TSDB<StdStorage>

pub fn new_file( name: &str, path: &str, sec_size: u32, max_size: u32, entry_max: usize, ) -> Result<Box<Self>, Error>

在 std 环境下，创建一个基于文件的 TSDB 实例。

此函数返回一个 Box<TSDB<StdStorage>>，以确保数据库实例在内存中的地址是稳定的， 防止因栈帧移动导致传递给 C 库的内部指针失效。

参数

• name: 数据库名称
• path: 数据库文件存储的目录
• sec_size: 扇区大小
• max_size: 数据库最大容量
• entry_max: 单个日志条目的最大长度

impl<S: NorFlash> TSDB<S>

pub fn new(storage: S) -> Self

创建一个未初始化的 KVDB 实例。

Arguments

• storage - 一个实现了 NorFlash trait 的存储实例。

pub fn set_name(&mut self, name: &str) -> Result<(), Error>

设置数据库名称，仅用于日志输出。

注意: 此方法必须在 init() 之前调用。

pub fn set_not_formatable(&mut self, enable: bool)

设置数据库为不可格式化模式。

在此模式下，如果数据库初始化时发现头部信息损坏，将返回错误而不是自动格式化。 注意: 此方法必须在 init() 之前调用。

pub fn not_formatable(&mut self) -> bool

检查数据库是否处于不可格式化模式。

pub fn set_rollover(&mut self, enable: bool)

启用或禁用翻转写入 (Rollover)。

启用后，当数据库写满时，最旧的数据将被新数据覆盖。 禁用后，数据库写满时 append 操作将返回 SavedFull 错误。 默认启用。

pub fn rollover(&self) -> bool

检查翻转写入 (Rollover) 是否已启用。

pub fn sec_size(&self) -> u32

获取当前扇区大小（字节）

pub fn last_time(&self) -> i64

获取上次追加 TSL 时的时间戳

pub fn init(&mut self, entry_max: usize) -> Result<(), Error>

初始化数据库。

此方法会加载现有数据库或根据 storage 的容量创建一个新的数据库。 它是实际与底层 C 库交互的入口。

参数

• default_kvs: (可选) 提供一组默认键值对。如果数据库是首次创建， 这些键值对将被写入数据库。

impl<S: NorFlash> TSDB<S>

pub fn append_with_timestamp( &mut self, timestamp: i64, data: &[u8], ) -> Result<(), Error>

追加带时间戳的日志条目

参数

• timestamp: 时间戳（毫秒级UNIX时间）
• data: 要存储的字节数据

返回

• Ok(()): 追加成功
• Err(Error): 存储失败（如空间不足）

pub fn set_status( &mut self, tsl: &mut TSLEntry, status: TSLStatus, ) -> Result<(), Error>

设置日志条目的状态（逻辑标记）

参数

• timestamp: 目标日志的时间戳
• status: 要设置的状态（如已同步、已删除）

应用场景

• 标记数据已上传至云端
• 逻辑删除旧数据（非物理删除）

pub fn count(&mut self, from: i64, to: i64, status: TSLStatus) -> usize

查询指定时间范围内特定状态的日志数量

参数

• from: 起始时间戳
• to: 结束时间戳
• status: 要筛选的状态

注意

• 结果通过底层API直接输出，未返回Rust值

pub fn tsdb_iter<F: FnMut(&mut TSDB<S>, &mut TSLEntry) -> bool + Send>( &mut self, callback: F, reverse: bool, )

迭代所有日志条目（支持正向/反向）

参数

• callback: 迭代回调函数，返回false可提前终止
• reverse: 是否反向迭代（最新条目优先）

pub fn tsdb_iter_by_time<F: FnMut(&mut TSDB<S>, &mut TSLEntry) -> bool + Send>( &mut self, from: i64, to: i64, callback: F, )

按时间范围迭代日志条目

参数

• from: 起始时间戳
• to: 结束时间戳 (包含)
• callback: 迭代回调函数 (包含)

pub fn reset(&mut self) -> Result<(), Error>

重置数据库（清除所有日志条目）

警告

• 此操作会删除所有数据，不可恢复
• 建议在初始化或测试时使用

pub fn get_value( &mut self, tsl_obj: &TSLEntry, ) -> Result<Option<Vec<u8>>, Error>

获取指定TSL条目的数据

参数

• tsl_obj: TSL对象（包含状态和长度信息）

返回

• Ok(Some(data)): 状态有效时返回数据
• Ok(None): 状态为UNUSED/DELETED时返回None
• Err(Error): 读取失败（如数据损坏）

pub fn open_read(&mut self, entry: TSLEntry) -> TSDBReader<'_, S>

打开TSL数据读取器

参数

• tsl_obj: 目标TSL对象（通过迭代获取）

返回

• TSDBReader: 实现了Read和Seek的读取器

Trait Implementations

impl<S: NorFlash> Drop for TSDB<S>

fn drop(&mut self)

Executes the destructor for this type.

impl<S: NorFlash> RawHandle for TSDB<S>

type Handle = *mut fdb_tsdb

fn handle(&self) -> Self::Handle

Care should be taken to use the returned ESP-IDF driver raw handle only while the driver is still alive, so as to avoid use-after-free errors.