persistence

persistence 提供SLE (Star Flash Low Energy) Service持久化数据管理功能，支持注册持久化回调函数以接收数据变更通知，以及配置PDL (Persistent Device List)数据和连接顺序数据到Service。

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_persistence.h"

接口清单

接口名称	功能简述
bs_sle_persistence_register_callbacks	注册SLE Service持久化回调函数，用于上报需要持久化的数据
bs_sle_persistence_unregister_callbacks	取消注册SLE Service持久化回调函数
bs_sle_config_pdl_data	配置PDL数据到Service
bs_sle_config_connect_order	配置连接顺序数据到Service

Functions

bs_sle_persistence_register_callbacks

errcode_t bs_sle_persistence_register_callbacks(bs_sle_persistence_callbacks_t *func)

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_persistence.h"

功能说明

注册SLE Service持久化回调函数，用于上报需要持久化的数据
当需要持久化的数据发生变化时，通过已注册的回调函数通知上层
回调函数结构体包含单条PDL数据上报回调和连接顺序数据上报回调

前置条件

调用时序约束：SLE Service已初始化完成
依赖关系：传入的回调函数结构体成员回调函数已正确实现

入参

名称	参数类型	详细说明	约束取值范围
func	bs_sle_persistence_callbacks_t *	持久化回调函数结构体指针	非NULL

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	注册成功
Other	其他错误码，参考errcode_sle_t	执行失败

bs_sle_persistence_unregister_callbacks

errcode_t bs_sle_persistence_unregister_callbacks(void)

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_persistence.h"

功能说明

取消注册SLE Service持久化回调函数
取消注册后，持久化数据变化时不再通知上层
与bs_sle_persistence_register_callbacks配对使用

前置条件

调用时序约束：需在bs_sle_persistence_register_callbacks成功注册之后调用
依赖关系：SLE Service已初始化完成

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	取消注册成功
Other	其他错误码，参考errcode_sle_t	执行失败

bs_sle_config_pdl_data

errcode_t bs_sle_config_pdl_data(uint8_t pdl_cnt, bs_sle_nv_obj_data_t *pdl_data)

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_persistence.h"

功能说明

配置PDL（Persistent Device List）数据到Service
将设备持久化信息写入Service，包括设备地址、链路密钥、加密算法等
pdl_cnt指定总存储数据条数，不大于SSF_PERSISTENCE_MAX_PDL_NUM

前置条件

调用时序约束：SLE Service已初始化完成
依赖关系：pdl_data指向的内存空间已申请成功

入参

名称	参数类型	详细说明	约束取值范围
pdl_cnt	uint8_t	总存储数据条数	0 ~ SSF_PERSISTENCE_MAX_PDL_NUM(10)
pdl_data	bs_sle_nv_obj_data_t *	PDL数据结构体指针	非NULL

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	配置成功
Other	其他错误码，参考errcode_sle_t	执行失败

bs_sle_config_connect_order

errcode_t bs_sle_config_connect_order(bs_sle_nv_conn_order_t *order)

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_persistence.h"

功能说明

配置连接顺序数据到Service
设置设备连接优先级顺序，影响设备重连时的连接顺序
连接顺序数据中的pdl_num不大于SSF_PERSISTENCE_MAX_PDL_NUM

前置条件

调用时序约束：SLE Service已初始化完成
依赖关系：order指向的内存空间已申请成功

入参

名称	参数类型	详细说明	约束取值范围
order	bs_sle_nv_conn_order_t *	连接顺序数据结构体指针	非NULL

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	配置成功
Other	其他错误码，参考errcode_sle_t	执行失败

Type definitions

errcode_t

typedef uint32_t errcode_t;

使用说明

作为本模块所有对外接口的返回值类型

bs_sle_pdl_report_callback

typedef void (*bs_sle_pdl_report_callback)(bs_sle_nv_single_pdl_data_t *param);

使用说明

作为bs_sle_persistence_callbacks_t结构体成员single_pdl_report_cb的类型，用于上报单条PDL数据。调用时机：注册该回调函数之后，需要持久化的数据发生变化时由Service调用

bs_sle_connect_order_report_callback

typedef void (*bs_sle_connect_order_report_callback)(bs_sle_nv_conn_order_t *param);

使用说明

作为bs_sle_persistence_callbacks_t结构体成员connect_order_report_cb的类型，用于上报连接顺序数据。调用时机：注册该回调函数之后，当设备连接顺序发生变化时由Service调用

Enumerations

bs_sle_write_single_pdl_to_nv_reason_type

typedef enum {
    WRITE_SINGLE_PDL_ADD,
    WRITE_SINGLE_PDL_UPDATE,
} bs_sle_write_single_pdl_to_nv_reason_type;

枚举成员	取值	描述
WRITE_SINGLE_PDL_ADD	0	新增单条PDL数据
WRITE_SINGLE_PDL_UPDATE	1	更新单条PDL数据

Structures

bs_sle_nv_device_data_t

typedef struct {
    uint8_t device_addr[SLE_ADDR_LEN];  /*!< Device Address */
    uint8_t link_key[SLE_LINK_KEY_LEN]; /*!< link key */
    uint8_t crypto_algo;                /*!< encryption algorithm type */
    uint8_t key_deriv_algo;             /*!< key distribution algorithm type */
    uint8_t integr_chk_ind;             /*!< integrity check indication */
    uint8_t is_bond;                    /*!< pair bonding indication */
    char device_name[SLE_NAME_MAX_LEN]; /*!< Device Name */
    uint8_t call_speaker_volume;        /*!< Call Speaker Volume */
    uint8_t media_volume;               /*!< Media Volume */
    uint8_t channel;                    /*!< Audio Channel */
    uint8_t reserved[29];               /*!< Reserved 30-byte field */
} bs_sle_nv_device_data_t;

成员说明

成员名称	数据类型	描述
device_addr	uint8_t[SLE_ADDR_LEN]	设备地址，长度为6字节
link_key	uint8_t[SLE_LINK_KEY_LEN]	链路密钥，长度为16字节
crypto_algo	uint8_t	加密算法类型
key_deriv_algo	uint8_t	秘钥分发算法类型
integr_chk_ind	uint8_t	完整性校验指示
is_bond	uint8_t	配对绑定指示
device_name	char[SLE_NAME_MAX_LEN]	设备名称，最大长度31字节
call_speaker_volume	uint8_t	通话扬声器音量
media_volume	uint8_t	媒体音量
channel	uint8_t	音乐声道
reserved	uint8_t[29]	预留字段

bs_sle_nv_obj_data_t

typedef struct {
    uint8_t device_num;                                                  /*!< Device Number In Obj */
    bs_sle_nv_device_data_t device_data[SSF_PERSISTENCE_MAX_DEVICE_NUM]; /*!< Device Information */
    uint8_t reserved[32];                                                /*!< Reserved 32-byte field */
} bs_sle_nv_obj_data_t;

成员说明

成员名称	数据类型	描述
device_num	uint8_t	Obj中设备数量，不大于SSF_PERSISTENCE_MAX_DEVICE_NUM
device_data	bs_sle_nv_device_data_t[SSF_PERSISTENCE_MAX_DEVICE_NUM]	设备信息数组，最多3个设备
reserved	uint8_t[32]	预留字段

bs_sle_nv_single_pdl_data_t

typedef struct {
    uint8_t index;                                        /*!< Index of nv data. */
    uint8_t pdl_num;                                      /*!< Total number of stored data entries,
                                                                not exceeding SSF_PERSISTENCE_MAX_PDL_NUM */
    bs_sle_write_single_pdl_to_nv_reason_type write_type; /*!< Reason of write nv data. */
    bs_sle_nv_obj_data_t pdl_data;                        /*!< obj data to nv. */
} bs_sle_nv_single_pdl_data_t;

成员说明

成员名称	数据类型	描述
index	uint8_t	存储数据索引
pdl_num	uint8_t	总存储数据条数，不大于SSF_PERSISTENCE_MAX_PDL_NUM
write_type	bs_sle_write_single_pdl_to_nv_reason_type	写数据原因
pdl_data	bs_sle_nv_obj_data_t	写obj数据

bs_sle_nv_conn_order_t

typedef struct {
    uint8_t pdl_num;                                     /*!< Total number of stored data entries,
                                                               not exceeding SSF_PERSISTENCE_MAX_PDL_NUM */
    uint8_t pdl_conn_order[SSF_PERSISTENCE_MAX_PDL_NUM]; /*!< Connection sequence of stored data entries */
} bs_sle_nv_conn_order_t;

成员说明

成员名称	数据类型	描述
pdl_num	uint8_t	总存储数据条数，不大于SSF_PERSISTENCE_MAX_PDL_NUM
pdl_conn_order	uint8_t[SSF_PERSISTENCE_MAX_PDL_NUM]	存储数据条目的连接顺序，最多10个条目

bs_sle_persistence_callbacks_t

typedef struct {
    bs_sle_pdl_report_callback single_pdl_report_cb;              /*!< Callback function for reporting
                                                                        a single pdl data. */
    bs_sle_connect_order_report_callback connect_order_report_cb; /*!< Callback function for reporting
                                                                        connection sequence data. */
} bs_sle_persistence_callbacks_t;

成员说明

成员名称	数据类型	描述
single_pdl_report_cb	bs_sle_pdl_report_callback	单条PDL数据上报回调函数
connect_order_report_cb	bs_sle_connect_order_report_callback	连接顺序数据上报回调函数

Macros

SSF_PERSISTENCE_MAX_DEVICE_NUM

#define SSF_PERSISTENCE_MAX_DEVICE_NUM 3

SSF_PERSISTENCE_MAX_PDL_NUM

#define SSF_PERSISTENCE_MAX_PDL_NUM 10

SLE_ADDR_LEN

#define SLE_ADDR_LEN        6

SLE_NAME_MAX_LEN

#define SLE_NAME_MAX_LEN    31

SLE_LINK_KEY_LEN

#define SLE_LINK_KEY_LEN    16