Include/plat_db.h

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