Include/plat_db.h

   1 /******************************************************************************
   2 *
   3 *   Copyright (c) 2020 ICT/CAS.
   4 *
   5 *   Licensed under the O-RAN Software License, Version 1.0 (the "Software License");
   6 *   you may not use this file except in compliance with the License.
   7 *   You may obtain a copy of the License at
   8 *
   9 *       https://www.o-ran.org/software
  10 *
  11 *   Unless required by applicable law or agreed to in writing, software
  12 *   distributed under the License is distributed on an "AS IS" BASIS,
  13 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 *   See the License for the specific language governing permissions and
  15 *   limitations under the License.
  16 *
  17 *******************************************************************************/
  18
  19
  20
  21
  22 #ifndef __PLAT_DB_H__
  23 #define __PLAT_DB_H__
  24
  25 #ifdef  __cplusplus
  26 extern "C"{
  27 #endif
  28
  29 #include "vos_types.h"
  30 #include "vos_lib.h"
  31
  32 /** 最多的表数 */
  33 #define DB_MAX_TABLE  200
  34
  35
  36 /** 表名最大长度 */
  37 #define DB_TABLE_NAME_LEN  40
  38
  39 /** 列名最大长度 */
  40 #define DB_COLUMN_NAME_LEN  40
  41
  42 /** 表的最大列数 */
  43 #define DB_TABLE_COLUMNS_MAX  40
  44
  45 /** 默认值最大长度 */
  46 #define DB_DEFAULTVAL_LEN  2048
  47
  48 /** 外键最大长度 */
  49 #define DB_FKEY_LEN (DB_TABLE_NAME_LEN+DB_COLUMN_NAME_LEN)
  50
  51 /** filer子元素最大个数 */
  52 #define DB_FILTER_SUB_NUM   8
  53
  54 #define DB_FILTER_SUB_VAL_NUM   8
  55
  56 /** INTEGER类型数据长度 */
  57 #define DB_INTEGER_LEN    8
  58
  59
  60 /** TIME类型数据长度 */
  61 #define DB_TIME_LEN    16
  62
  63
  64 /** 时间字符串数据长度 */
  65 #define DB_TIME_STR_MAX_LEN    22
  66
  67 /** MAC地址类型数据长度 */
  68 #define DB_MAC_ADDR_STR_MAX_LEN    18
  69
  70 /** IPV4地址类型数据长度 */
  71 #define DB_IPV4_ADDR_STR_MAX_LEN   16
  72
  73 /** IPV6地址类型数据长度 */
  74 #define DB_IPV6_ADDR_STR_MAX_LEN   40
  75
  76
  77 #define DB_FILTER_OP_STR_LEN  10
  78
  79 /** 初始化函数名最大长度 */
  80 #define DB_TABLE_INIT_FUNC_NAME_LEN  100
  81
  82 /** 数据库的数据类型 */
  83 typedef enum DB_data_type_e{
  84     DB_DATA_TYPE_INTEGER        = 1L,  ///< 数值型
  85     DB_DATA_TYPE_STR               ,  ///< 字符串型
  86     DB_DATA_TYPE_DATETIME          ,  ///< 时间型
  87     DB_DATA_TYPE_MAC               ,  ///< MAC地址型
  88     DB_DATA_TYPE_IPV4_ADDR         ,  ///< IPv4地址型
  89     DB_DATA_TYPE_IPV6_ADDR         ,  ///< IPv6地址型
  90     DB_DATA_TYPE_BUFFER            ,  ///< buffer型
  91     DB_DATA_TYPE_MAX
  92 }DB_data_type_t;
  93
  94
  95 /** 数据库的查询的比较类型 */
  96 typedef enum DB_filter_sub_type_e{
  97     DB_FILTER_SUB_TYPE_EQUAL        = 1,  ///< 相等
  98     DB_FILTER_SUB_TYPE_N_EQUAL         ,  ///< 不相等
  99     DB_FILTER_SUB_TYPE_GREAT           ,  ///< 大于
 100     DB_FILTER_SUB_TYPE_LESS            ,  ///< 小于
 101     DB_FILTER_SUB_TYPE_GREAT_EQ        ,  ///< 大于等于
 102     DB_FILTER_SUB_TYPE_LESS_EQ         ,  ///< 小于等于
 103     DB_FILTER_SUB_TYPE_INCLUDE         ,  ///< 包含
 104     DB_FILTER_SUB_TYPE_EXCLUDE         ,  ///< 不包含
 105     DB_FILTER_SUB_TYPE_MAX
 106 }DB_filter_sub_type_t;
 107
 108 /** filter的组合方式 */
 109 typedef enum DB_filter_option_e{
 110     DB_FILTER_OPTION_AND        = 1,  ///< 与
 111     DB_FILTER_OPTION_OR            ,  ///< 或
 112     DB_filter_TYPE_MAX
 113 }DB_filter_option_t;
 114
 115 /** 排序方式 */
 116 typedef enum DB_order_type_e{
 117     DB_ORDER_TYPE_ASCEND        = 0,  ///< 升序(默认)
 118     DB_ORDER_TYPE_DESCEND       = 1,  ///< 降序
 119     DB_ORDER_TYPE_MAX
 120 }DB_order_type_t;
 121 #define  DB_ORDER_TYPE_DESCEND_STR "DESC"
 122
 123 /** 排序信息 */
 124 typedef struct DB_order_s{
 125     CHAR col_name[DB_COLUMN_NAME_LEN];
 126     DB_order_type_t type;  ///< 默认升序
 127 }DB_order_t;
 128
 129
 130 /** 数据库数据的值 */
 131 typedef union DB_data_val_u{
 132     LONG integerVal;
 133     CHAR strVal[DB_DEFAULTVAL_LEN];
 134     CHAR datetimeVal[DB_DEFAULTVAL_LEN];
 135     CHAR macVal[DB_MAC_ADDR_STR_MAX_LEN];
 136     CHAR ipv4_addrVal[DB_IPV4_ADDR_STR_MAX_LEN];
 137     CHAR ipv6_addrVal[DB_IPV6_ADDR_STR_MAX_LEN];
 138 }VOS_PACKED DB_data_val_t;
 139
 140
 141 /** 列信息 */
 142 typedef struct DB_column_info_s{
 143     CHAR name[DB_COLUMN_NAME_LEN];              ///< 列名
 144     LONG type;                                  ///< 数据的类型
 145     LONG size;                                  ///< 对于BUFFER和STR 类型，代表BUFFER 和 STR(包含字符串结尾 '\0') 占用的字节数
 146     LONG pkey;                                  ///< 主键标志
 147     CHAR fkey[DB_FKEY_LEN];                     ///< 外键,表名+.+列名的字符串，格式为 table(column)，字符串长度为 0 则表示不是外键
 148     DB_data_val_t defaultVal;                   ///< 默认值
 149 }VOS_PACKED DB_column_info_t;
 150
 151 /** 数据库句柄 */
 152 typedef struct DB_database_s{
 153     CHAR path[FILE_PATH_MAX];       ///< 文件路径
 154     VOID *handle;                   ///< 被打开的数据库
 155     LONG seqID;
 156 }DB_database_t;
 157
 158 /** 数据库查询结果的行句柄 */
 159 typedef ULONG DB_row_handle_t;
 160
 161
 162 /** 数据初始化函数回调函数原型
 163 * 无参数，返回 VOS_OK 表示成功
 164 */
 165 typedef LONG (*DB_table_init_func_t)(VOID);
 166
 167 /** 表信息 */
 168 typedef struct DB_table_info_s{
 169     CHAR name[DB_TABLE_NAME_LEN];       ///< name         表名
 170     LONG max_row;                       ///< 静态表标志，1为静态表，0为动态表
 171     DB_table_init_func_t table_init_func;    ///< 表初始化函数，可以为空
 172     CHAR table_init_func_name[DB_TABLE_INIT_FUNC_NAME_LEN];
 173 }DB_table_info_t;
 174
 175 /** filer子元素 */
 176 typedef struct DB_query_filter_sub_s{
 177     CHAR                 col_name[DB_COLUMN_NAME_LEN];       ///< name         表名
 178     DB_data_val_t        val[DB_FILTER_SUB_VAL_NUM];
 179     DB_filter_sub_type_t sub_type;
 180     DB_filter_option_t   option;
 181 }DB_query_filter_sub_t;
 182
 183 /** filer */
 184 typedef struct DB_query_filter_s{
 185     DB_query_filter_sub_t sub[DB_FILTER_SUB_NUM];
 186     DB_filter_option_t    option;
 187 }DB_query_filter_t;
 188
 189
 190 /** 排序方式 */
 191 typedef enum DB_ret_code_e{
 192     DB_RET_CODE_OK                     = 0,  ///< 执行成功
 193     DB_RET_CODE_table_already_exist       ,  ///< 表已存在
 194     DB_RET_CODE_table_not_exist       ,      ///< 表已存在
 195     DB_RET_CODE_table_info_already_exist  ,  ///< 表的信息在数据库管理表中已存在(由数据库模块问题导致)
 196     DB_RET_CODE_col_info_already_exist  ,    ///< 表的列信息在数据库管理表中已存在(由数据库模块问题导致)
 197     DB_RET_CODE_table_info_not_exist  ,      ///< 表的信息在数据库管理表中不存在(由数据库模块问题导致)
 198     DB_RET_CODE_col_info_not_exist  ,        ///< 表的列信息在数据库管理表不中已存在(由数据库模块问题导致)
 199     DB_RET_CODE_table_info_add_error  ,      ///< 数据库模块添加表信息失败
 200     DB_RET_CODE_col_info_add_error  ,        ///< 数据库模块添加列信息失败
 201     DB_RET_CODE_get_col_size_error  ,        ///< 获取列大小失败
 202     DB_RET_CODE_row_data_have_more  ,        ///< row_handle 中还有数据
 203     DB_RET_CODE_row_data_done       ,        ///< row_handle 中没有数据
 204     DB_RET_CODE_row_data_pk_exist       ,    ///< 添加的数据主键冲突
 205     DB_RET_CODE_table_full       ,           ///< 表已满，无法在添加数据
 206
 207     DB_RET_CODE_error,                       ///< 其他错误
 208     DB_RET_CODE_max,                         ///<
 209 }DB_ret_code_t;
 210
 211
 212 /**
 213  * 打开平台数据库
 214  * @param[out]   db           成功时返回被打开的数据
 215  * @return      成功返回 VOS_OK，失败则返回其他
 216  */
 217 LONG DB_open_plat_db(DB_database_t *db);
 218
 219
 220 /**
 221  * 关闭平台数据库
 222  * @param[in ]   db           要操作的数据库
 223  * @return      成功返回 VOS_OK，失败则返回其他
 224  */
 225 LONG DB_close_plat_db(DB_database_t *db);
 226
 227
 228 /**
 229  * 查看表是否存在
 230  * @param[in ]   db           要操作的数据库
 231  * @param[in ]   table_name   表名
 232  * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 233  * @param[in ]   timeout      等待执行结果的时间，单位 秒
 234  * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 235  */
 236 BOOL DB_table_exist(DB_database_t *db,const CHAR *table_name,
 237                         LONG *retCode,LONG timeout);
 238
 239
 240 /**
 241  * 在指定数据库中创建表
 242  * @param[in ]   db           要操作的数据库
 243  * @param[in ]   table        表信息
 244  * @param[in ]   cols         表的列定义数组，数组最后一个成员的name为空做为数组结尾
 245  * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 246  * @param[in ]   timeout      等待执行结果的时间，单位 秒
 247  * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 248  */
 249 LONG DB_table_create(DB_database_t *db,DB_table_info_t *table,DB_column_info_t cols[],
 250                             LONG *retCode,LONG timeout);
 251
 252
 253 /**
 254  * 在指定数据库中删除表
 255  * @param[in ]   db           要操作的数据库
 256  * @param[in ]   name         表名
 257  * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 258  * @param[in ]   timeout      等待执行结果的时间，单位 秒
 259  * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 260  */
 261 LONG DB_table_delete(DB_database_t *db,const CHAR name[DB_TABLE_NAME_LEN],
 262                                 LONG *retCode,LONG timeout);
 263
 264
 265 /**
 266  * 向表中插入一行数据
 267  * @param[in ]   db           要操作的数据库
 268  * @param[in ]   table_name   要操作的表名
 269  * @param[in ]   data         要插入的数据，需按照创建表时定义的按顺序和大小排列每项数据，
 270                               可以传入按1字节对齐的结构体。
 271  * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 272  * @param[in ]   timeout      等待执行结果的时间，单位 秒
 273  * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 274  */
 275 LONG DB_table_row_add(DB_database_t *db,const CHAR table_name[DB_TABLE_NAME_LEN],VOID *data,
 276                                     LONG *retCode,LONG timeout);
 277
 278
 279 /**
 280 * 查询数据
 281 * @param[in ]   db           要操作的数据库
 282 * @param[in ]   table_name   要操作的表名
 283 * @param[out]   row_handle   查询到的行句柄
 284 * @param[in ]   filter       查询时的过滤条件，为NULL 表示没有过滤条件，查询所有行
 285 * @param[in ]   filter_num   filter的个数
 286 * @param[in ]   order        查询结果排序方式
 287 * @param[in ]   order_num    order的个数
 288 * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 289 * @param[in ]   timeout      等待执行结果的时间，单位 秒
 290 * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 291 */
 292 LONG DB_table_row_query(DB_database_t *db,const CHAR table_name[DB_TABLE_NAME_LEN],DB_row_handle_t *row_handle,
 293                             DB_query_filter_t filter[],LONG filter_num,DB_order_t order[],LONG order_num,
 294                             LONG *retCode,LONG timeout);
 295
 296
 297
 298 /**
 299 * 获取行句柄当前行数据，并自动指向下一行，当没下一行数据时，句柄会被销毁，不可再用
 300 * @param[in ]   db           要操作的数据库
 301 * @param[in ]   table_name   要操作的表名
 302 * @param[in]    row_handle   行句柄
 303 * @param[out]   data         获取到的数据，按照创建表时定义的按顺序和大小排列每项数据，
 304                              可以传入按1字节对齐的结构体指针。
 305 * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 306 * @param[in ]   timeout      等待执行结果的时间，单位 秒
 307 * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 308 */
 309 LONG DB_table_row_data_pop(DB_database_t *db,const CHAR table_name[DB_TABLE_NAME_LEN],
 310                                         DB_row_handle_t *row_handle,VOID *data,
 311                                         LONG *retCode,LONG timeout);
 312
 313 /**
 314 * 销毁行句柄
 315 * @param[in ]   db           要操作的数据库
 316 * @param[in ]   table_name   要操作的表名
 317 * @param[in ]   row_handle   行句柄
 318 * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 319 * @param[in ]   timeout      等待执行结果的时间，单位 秒
 320 * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 321 */
 322 LONG DB_table_row_handle_destroy(DB_database_t *db,const CHAR table_name[DB_TABLE_NAME_LEN],DB_row_handle_t *row_handle,
 323                                             LONG *retCode,LONG timeout);
 324
 325
 326 /**
 327 * 删除行
 328 * @param[in ]   db           要操作的数据库
 329 * @param[in ]   table_name   要操作的表名
 330 * @param[in ]   filter       删除时的过滤条件，为NULL 表示没有过滤条件，删除所有行
 331 * @param[in ]   filter_num   filter的个数
 332 * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 333 * @param[in ]   timeout      等待执行结果的时间，单位 秒
 334 * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 335 */
 336 LONG DB_table_row_delete(DB_database_t *db,const CHAR table_name[DB_TABLE_NAME_LEN],
 337                             DB_query_filter_t filter[],LONG filter_num,
 338                             LONG *retCode,LONG timeout);
 339
 340
 341
 342 /**
 343 * 更新行
 344 * @param[in ]   db           要操作的数据库
 345 * @param[in ]   table_name   要操作的表名
 346 * @param[in ]   newData      新的数据，需按照创建表时定义的按顺序和大小排列每项数据，
 347                              可以传入按1字节对齐的结构体。
 348 * @param[in ]   filter       更新时的过滤条件，为NULL 表示没有过滤条件，更新所有行
 349 * @param[in ]   filter_num   filter的个数
 350 * @param[in ]   col          只会用到name成员，用于更新指定的列，为NULL 表示更新匹配行的每一列,数组最后一个成员的name为空做为数组结尾
 351 * @param[in ]   col_num      col的个数
 352 * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 353 * @param[in ]   timeout      等待执行结果的时间，单位 秒
 354 * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 355 */
 356 LONG DB_table_row_update(DB_database_t *db,const CHAR table_name[DB_TABLE_NAME_LEN],VOID *newData,
 357                             DB_query_filter_t filter[],LONG filter_num,DB_column_info_t col[],LONG col_num,
 358                             LONG *retCode,LONG timeout);
 359
 360
 361 /**
 362 * 计算行数
 363 * @param[in ]   db           要操作的数据库
 364 * @param[in ]   table_name   要操作的表名
 365 * @param[out]   row_count    查询到的行数
 366 * @param[in ]   filter       查询时的过滤条件，为NULL 表示没有过滤条件，查询所有行
 367 * @param[in ]   filter_num   filter的个数
 368 * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 369 * @param[in ]   timeout      等待执行结果的时间，单位 秒
 370 * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 371 */
 372 LONG DB_table_row_count(DB_database_t *db,const CHAR table_name[DB_TABLE_NAME_LEN],LONG *row_count,
 373                             DB_query_filter_t filter[],LONG filter_num,
 374                             LONG *retCode,LONG timeout);
 375
 376 /**
 377 * 覆盖最早插入的数据，用于表行数到达上限的覆盖操作
 378 * @param[in ]   db           要操作的数据库
 379 * @param[in ]   table_name   要操作的表名
 380 * @param[in ]   newData      新的数据，需按照创建表时定义的按顺序和大小排列每项数据，
 381                              可以传入按1字节对齐的结构体。
 382 * @param[out]   retCode      数据库执行结果，如果不关心可以填 NULL，如果关心需要传入timeout，等待时间
 383 * @param[in ]   timeout      等待执行结果的时间，单位 秒
 384 * @return      返回向数据库模块发送消息的结果，成功返回 VOS_OK，失败则返回其他，
 385 */
 386 LONG DB_table_overwrite_first_row( DB_database_t *db,const CHAR table_name[DB_TABLE_NAME_LEN],VOID *newData,
 387                                             LONG *retCode,LONG timeout);
 388
 389
 390 /**
 391 * 将DB 的error code转换成字符串
 392 * @param[in ]   code           错误码
 393 * @return      返回错误码对应的字符串
 394 */
 395 const CHAR *DB_err_msg(LONG code);
 396
 397
 398 #ifdef  __cplusplus
 399 }
 400 #endif  /* end of __cplusplus */
 401
 402 #endif  /* end of __PLAT_DB_H__ */