【BBF系列协议】Data Models Library数据模型库设计与实现

帐篷Li-物联网布道师

发布于 2024-03-20 08:18:20

920

发布于 2024-03-20 08:18:20

Data Models Library (dmlib)

dmlib是一种数据模型库实现，将TR069系列数据模型拆分成对象（Object）和参数（Paramters）来定义标准操作接口，可用于通过远程控制协议，如TR-069/CWMP 或 TR-369/USP管理的CPE设备上。这个库主要特性如下:

特性	描述
协议无关,跨平台	解耦cwmp协议独立成模块,提供统一的接口标准来适配不同平台的操作
可拓展	可适配tr369，mqtt等其他协议,可拓展tr181,tr098,tr104等数据模型规范
统一数据模型操作入口	该库提供了使用统一入口添加新参数或扩展现有数据模型树的机制
外部数据接口库封装	该库提供了UCI、JSON和动态内存管理等统一接口

dmlib的设计

`dmlib` 的代码结构:

├── dmtree
│   └── tr098
│       ├── root.c
│       ├── deviceinfo.c
│       └── wandevice.c
├── include	
│   ├── dmcommon.h
│   ├── dmentry.h
│   ├── dmjson.h
│   ├── dmmem.h
│   ├── dmtr098.h
│   ├── dmuci.h
│   └── dmtree
│      	 ├── root.h
│     	 ├── deviceinfo.h
│      	 └── wandevice.h
├── dmentry.c
├── dmtr098.c
├── dmcommon.c
├── dmjson.c
├── dmmem.c
└── dmuci.c

dmtree 文件夹包含所有支持的数据模型，
- tr098 : TR-098 数据模型操作接口实现，按照操作对象(Object)来拆分c文件,方便后期维护
- other : 可自行拓展不同数据模型，如：tr181，tr104等
dmentry.c 主要实现TR069协议对参数和对象的CRUD操作，dmctx全局上下文的初始化和销毁以及参数值变化更新等入口函数。
dmtr098.c 主要实现参数树的遍历和CRUD操作回调函数的挂载
dmcommon.c 公共的工具类处理函数
dmmem.c 统一的动态内存管理接口
dmuci.c UCI接口封装

`dmlib` 主要数据结构

操作上下文对象（dmctx）

结构体成员	描述
stop	dm_browse遍历停止标志
method_param	参数操作回调函数
method_obj	对象操作回调函数
checkobj	对象路径校验回调函数
checkleaf	参数路径校验回调函数
list_parameter	操作结果返回值链表
set_list_tmp	setvalue的临时保存链表
list_fault_param	操作错误返回值链表
dm_entryobj	操作数据模型树
nextlevel	getnames是否获取下一级
faultcode	操作错误码
setaction	setvalue/setnotification的动作：VALUECHECK or VALUESET
in_param	操作入参
in_notification	setnotification的动作的设置值
in_value	setvalue的设置值
addobj_instance	addobject新增实例的下标返回值
instance_mode	实例模式：别名（INSTANCE_MODE_ALIAS） or 数字（INSTANCE_UPDATE_NUMBER）
inparam_isparam	操作入参是否为参数(DMLEAF)
findparam	操作入参全匹配改标志置:‘1’
add_list_value_change	valueschange保存链表回调函数
send_active_value_change	valueschange事件发送回调函数

对象定义（DMOBJ）

结构体成员	描述
obj	对象名称的字符串。示例：“Bridging”、“IP”、“DeviceInfo”、“WiFi”
permission	对象的权限。&DMREAD 或 &DMWRITE 。如果是 &DMWRITE，则可以添加/删除此对象的实例
addobj	用于在此对象下添加新实例的函数。当ACS/Controller调用此对象的AddObject时，将触发此函数
delobj	删除此对象下实例的函数。当ACS/Controller调用此对象实例的DeleteObject时，将触发此函数
checkobj	对象依赖检查，一般为空，忽略该检查
browseinstobj	此函数允许浏览此对象下的所有实例
nextobj	指向包含子对象列表的 DMOBJ 数组的指针
leaf	指向包含子参数列表的 DMLEAF 数组的指针

参数定义（DMLEAF）

结构体成员	描述
parameter	参数名称的字符串。示例：“Enable”、“Status”、“Name”
permission	参数的权限。 &DMREAD 或 &DMWRITE 。如果是 &DMWRITE，则可以为该参数设置一个值
type	参数的类型：DM_STRING，DM_BOOL，DM_UNINT，…
getvalue	获取此参数值的函数
setvalue	设置此参数值的函数
forced_inform	该参数为强制上报参数
notification	参数属性默认值

多实例遍历函数实现（browseinstobj）

浏览功能允许浏览当前对象的所有实例，并将它们链接到数据模型树。在此函数中，需要定义两个函数：

通过函数来检索实例：例如：
- uci_foreach_sections : 通过uci.sections来遍历实例
- handle_update_instance: 通过指定属性来获取实例下标.
函数链接实例：我们需要为每个实例调用 DM_LINK_INST_OBJ() 函数，以便将实例链接到数据模型树。我们还需要指定此实例级别的data。此data可稍后在子对象和参数函数 (Get/Set/Add/Delete) 中使用。

注意1: 遍历函数仅针对多实例对象开发.

参数树遍历规则

参数树在初始化时（dm_ctx_init_custom）传入：dmctx->dm_entryobj
入参路径传入：dmctx->in_param = inparam
CRUD操作注册不同的回调函数，主要注册四个回调函数：
- 对象操作回调函数：dmctx->method_obj
- 参数操作回调函数：dmctx->method_param
- 对象校验回调函数：dmctx->checkobj
- 参数校验回调函数：dmctx->checkleaf
结果存放于：dmctx->list_parameter
多个set的操作临时值存放于：dmctx->set_list_tmp，由dm_entry_apply统一生效
错误存放于：dmctx->list_fault_param
添加实例下标存放于：dmctx->addobj_instance

示例：
get/set路径：InternetGatewayDevice.DeviceInfo.Manufacturer
InternetGatewayDevice.   entryobj->nextobj --> dm_browse
InternetGatewayDevice.DeviceInfo. entryobj->leaf --> dm_browse_leaf
InternetGatewayDevice.DeviceInfo.Manufacturer dmctx->method_param --> strcmp mark --> (get_cmd/set_cmd)

get/set多实例路径：InternetGatewayDevice.WANDevice.1.WANConnectionDevice.Params
InternetGatewayDevice.   entryobj->nextobj --> dm_browse
InternetGatewayDevice.WANDevice.   entryobj->browseinstobj --> DM_LINK_INST_OBJ
InternetGatewayDevice.WANDevice.1   entryobj->nextobj --> dm_browse
InternetGatewayDevice.WANDevice.1.WANConnectionDevice   entryobj->leaf --> dm_browse_leaf
InternetGatewayDevice.WANDevice.1.WANConnectionDevice.Params   dmctx->method_param --> strcmp mark --> (get_cmd/set_cmd)

add:InternetGatewayDevice.Layer3Forwarding.Forwarding.
InternetGatewayDevice.   entryobj->nextobj --> dm_browse
InternetGatewayDevice.Layer3Forwarding.   entryobj->nextobj --> dm_browse
InternetGatewayDevice.Layer3Forwarding.Forwarding.   check mark --> dmctx->method_obj --> (addobj) --> 返回新增实例addobj_instance

del:InternetGatewayDevice.Layer3Forwarding.Forwarding.1.
InternetGatewayDevice.   entryobj->nextobj --> dm_browse
InternetGatewayDevice.Layer3Forwarding.   entryobj->nextobj --> dm_browse
InternetGatewayDevice.Layer3Forwarding.Forwarding.   entryobj->browseinstobj --> DM_LINK_INST_OBJ
InternetGatewayDevice.Layer3Forwarding.Forwarding.1.   check mark --> dmctx->method_obj --> (delobj)

InternetGatewayDevice. 
    --> DeviceInfo(nextobj). --> Manufacturer(leaf)
    --> ManagementServer(nextobj). --> xxx(leaf)
    --> Layer3Forwarding(nextobj). --> xxx(leaf)
        --> Forwarding(nextobj). --> xxx(leaf)

关键函数

dmentry.c 该文件中所有入口函数都为关键函数
- dm_ctx_init : 初始化uci,操作结果等临时链表，参数树等全局上下文成员
- dm_ctx_clean : 销毁uci，清除操作结果等临时链表以及动态分配的内存
- dm_entry_load_enabled_notify : 注册发送值变化事件回调和存放参数链表回调，初始化时加载
- dm_entry_reload_enabled_notify : 值变化更新，定时更新需要主动上报的值变化
- dm_entry_param_method : 数据模型树CRUD操作入口
- dm_entry_apply : set值和属性统一生效函数
dmtr098.c 数据模型树的主要遍历逻辑
- dm_browse : 遍历数据模型树的主入口
- dm_browse_leaf : 遍历参数叶子节点函数
- dm_entry_*（get_value/set_value/get_name/add_object/delete_object） : 数据模型树CRUD操作具体实现

dmlib的库依赖

为了成功编译该库 , 下面的库是必须的:

Dependency	Link	License
libuci	https://git.openwrt.org/project/uci.git	LGPL 2.1
libubox	https://git.openwrt.org/project/libubox.git	BSD
libjson-c	https://s3.amazonaws.com/json-c_releases	MIT