Include/vos_cli.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 #ifndef __VOS_CLI_H__
  22 #define __VOS_CLI_H__
  23 #include "vos_types.h"
  24
  25 #ifdef    __cplusplus
  26 extern "C"
  27 {
  28 #endif /* __cplusplus */
  29
  30 /** 历史命令记录条数 */
  31 #define VTY_MAXHIST 20
  32
  33 /** 命令行提示符长度 */
  34 #define VTY_CMD_PROMPT_MAX  64
  35
  36 /** 节点嵌套层数 */
  37 #define VTY_NODE_HIS_MAX 8
  38
  39 /* 换行字符串 */
  40 #define VTY_NEWLINE  ((vty->type == VTY_TERM) ? "\r\n" : "\r\n")
  41
  42 /** show 命令说明字符串 */
  43 #define SHOW_STR "Show running system information\n"
  44
  45 /** config 命令说明字符串 */
  46 #define CONFIG_STR "Config system's setting\n"
  47
  48 /** no 命令说明字符串 */
  49 #define NO_STR "Negate a command or set its defaults\n"
  50
  51 /** debug 命令说明字符串 */
  52 #define DEBUG_STR "Debugging functions\n"
  53
  54 /** 命令回调函数返回值 命令执行 OK */
  55 #define CMD_RET_OK       (0)
  56
  57 /** 命令回调函数返回值 命令执行 ERROR */
  58 #define CMD_RET_ERROR    (1)
  59
  60
  61
  62 /** VOS 预定义的节点 */
  63 enum node_type
  64 {
  65     VOS_CLI_VIEW_NODE,              ///<  View node. Default mode of vty interface.
  66     VOS_CLI_CONFIG_NODE,            ///<  Config node. Default mode of config file.
  67     VOS_CLI_DEBUG_HIDDEN_NODE,      ///<  Debug hidden node.
  68     VOS_CLI_CONFIRM_ACTION_NODE,    ///<  Confirm action.
  69     VOS_CLI_RESV_MAX_NODE           ///<  Vos max reserved node ID
  70 };
  71
  72
  73 struct exit_use_node
  74 {
  75     int   node_in_use;                          ///<  使用标记
  76     enum node_type node;                        ///<  节点ID
  77     void *context_data;                         ///<  记录命令行上下文数据，如进入端口节点可以记录端口号
  78     INT  context_data_need_free;                ///<  标记context_data 是否需要free，在exit 命令中会执行VOS_free
  79     CHAR  vty_cmd_prompt[ VTY_CMD_PROMPT_MAX ]; ///<  自定义提示符
  80 };
  81
  82
  83 /** VTY 结构体，只需关心fd之前的成员. */
  84 struct vty
  85 {
  86     char vty_cmd_prompt[VTY_CMD_PROMPT_MAX];   ///<  自定义提示符
  87
  88     VOID *context_data;                        ///<  记录命令行上下文数据，如进入端口节点可以记录端口号
  89
  90     INT context_data_need_free;                ///<  标记context_data 是否需要free，在exit 命令中会执行VOS_free
  91
  92     int (*action_func) (struct vty *vty);      ///<  confirm action 的回调函数
  93
  94     int (*no_action_func) (struct vty *vty);   ///<  refuse action  的回调函数
  95
  96     /* 文件描述符 */
  97     int fd;
  98
  99     /* 当前节点ID */
 100     enum node_type node;
 101
 102     /* 上一节点ID */
 103     enum node_type prev_node;
 104
 105     /* VTY 类型 */
 106     enum { VTY_TERM, }type;
 107
 108     /* client IP */
 109     char *address;
 110
 111     /* vty 输出缓冲区 */
 112     struct buffer *obuf;
 113
 114     /* obuf 的锁 */
 115     LONG  Sem_obuf ;
 116
 117     /* vty 命令输入缓冲区 */
 118     char *buf;
 119
 120     /* 当前光标的位置 */
 121     int cp;
 122
 123     /* 当前输入的长度 */
 124     int length;
 125
 126     /* buf 的大小. */
 127     int max;
 128
 129     /* 历史命令 */
 130     char *hist[VTY_MAXHIST];
 131
 132     /* 查看历史命令时记录当前索引 */
 133     int hp;
 134
 135     /* 历史命令条数 */
 136     int hindex;
 137
 138     struct exit_use_node node_his_save[VTY_NODE_HIS_MAX];
 139
 140     /* 转义字符状态. */
 141     unsigned char escape;
 142
 143     /* vty 状态. */
 144     enum { VTY_NORMAL, VTY_CLOSE, VTY_MORE, VTY_START, VTY_CONTINUE, VTY_IOREDIRECT }status;
 145
 146     /* telnet IAC handling */
 147     unsigned char iac;
 148
 149     /* telnet IAC SB handling */
 150     unsigned char iac_sb_in_progress;
 151     /* telnet IAC SB buffer */
 152     struct buffer *sb_buffer;
 153
 154     /* 窗口宽度，暂未使用 */
 155     int width;
 156     /* 窗口高度，lines为0时有效 */
 157     int height;
 158
 159     /* 一次输出的做大行数 */
 160     int lines;
 161
 162     /* 已进入config节点，用于限制多用户进入config */
 163     int config;
 164
 165     /* 输入监控任务 */
 166     struct cl_lib_thread *t_read;
 167     /* 输出监控任务 */
 168     struct cl_lib_thread *t_write;
 169
 170     /*VTY 超时时间，秒 */
 171     unsigned long v_timeout;
 172
 173     /*VTY 超时处理任务 */
 174     struct cl_lib_thread *t_timeout;
 175
 176     /*VTY 退出标志位 */
 177     unsigned short cl_vty_exit;
 178
 179     /* vty 接入类型console，telnet， telnet IPv6 */
 180     int conn_type;
 181
 182     /* vty 接入用户名 */
 183     char *user_name;
 184
 185     /* vty 会话任务 */
 186     struct cl_lib_thread_master *sub_thread_master;
 187
 188     /* vty 会话任务handle */
 189     VOS_HANDLE sub_task_id;
 190
 191     /* vty 调试标志位 */
 192     unsigned short debug_monitor;
 193
 194     /************************************
 195     frozen vty in and(or) out
 196     used for if a command can't return immediately
 197     then call frozen to freeze vty's in and(or) out
 198     call unfrozen when finished.
 199     1: freezed
 200     0: unfreezed
 201     ***********************************/
 202     unsigned short frozen;
 203
 204     //VOS_SYSLOG_MONITOR_CONF  monitor_conf;
 205     int veryBigOutLineCount;
 206     int veryBigOutNoFirst;
 207
 208     /* vty 引用计数，当引用计数为0的时候调用vty_close释放内存 */
 209     int ncount;
 210 };
 211
 212
 213 /** cl_vector 动态数组指针 */
 214 struct _cl_vector
 215 {
 216     unsigned int max;       ///< 当前最大索引加1
 217     unsigned int alloced;   ///< 数组大小 */
 218     void **index;           ///< 指针数组
 219 };
 220 typedef struct _cl_vector *cl_vector;
 221
 222
 223 /** 命令结构体 */
 224 struct cmd_element
 225 {
 226     char *string;                ///< 命令字符串，多个用空格分隔的单词组成的句子
 227     int (*func) (struct cmd_element *, struct vty *, int, char **); ///< 命令回调函数
 228     char *doc;                   ///< 命令说明，对命令字符串中的每个单词进行说明
 229     int msg_flag;        ///< 命令类型标识，当前只有 DEFUN_FLAG 类型
 230     cl_vector strvec;    ///< 将 string和doc 拆分后放入该数组中 ,存放struct desc
 231     int cmdsize;                 ///< string 中单词个数
 232     cl_vector subconfig; ///< 将 string中可以重复的单词的重复位置和重复次数等
 233 };
 234
 235
 236 /** 命令节点结构体 */
 237 struct cmd_node
 238 {
 239     enum node_type node_id;           ///< 节点ID
 240     char prompt[VTY_CMD_PROMPT_MAX];  ///< 节点提示符
 241     cl_vector cmd_vector;             ///< 节点命令数组
 242 };
 243
 244
 245 #define DEFUN_FLAG     0
 246
 247 /**
 248  * 命令行定义宏
 249  * @param[in]   funcname   回调函数的函数名
 250  * @param[in]   cmdname    命令变量的变量名
 251  * @param[in]   cmdstr     命令字符串
 252  * @param[in]   helpstr    命令字符串中各个单词的注解
 253  * @return      返回输出的字节数
 254  */
 255 #define DEFUN(funcname, cmdname, cmdstr, helpstr)   \
 256         int funcname (struct cmd_element *, struct vty *, int, char **);\
 257         struct cmd_element cmdname =   {cmdstr,     funcname,     helpstr , DEFUN_FLAG};\
 258         int funcname  (struct cmd_element *self, struct vty *vty, int argc, char **argv)
 259
 260
 261 /**
 262  * 命令行回调函数中的标准输出函数,
 263  * 注意 LONG 输出时，要用%ld,或%lx
 264  * @param[in]   vty     vty
 265  * @param[in]   format  格式字符串
 266  * @param[in]   ...     要输出的变量
 267  * @return      返回输出的字节数
 268  */
 269 INT vty_out ( struct vty * vty, const CHAR * format, ... );
 270
 271 /**
 272  * 创建并安装命令节点
 273  * @param[in]   prompt         节点提示符，用于命令行提示符的显示
 274  * @return      成功返回 一个新节点的指针,失败返回NULL
 275  */
 276 struct cmd_node *VOS_cli_create_node(char prompt[VTY_CMD_PROMPT_MAX]);
 277
 278
 279 /**
 280  * 把命令安装到指定节点
 281  * @param[in]   node_id     节点ID
 282  * @param[in]   cmd         命令
 283  * @return      成功返回 VOS_OK,失败返回其他
 284  */
 285 VOID VOS_cli_install_element( enum node_type node_id, struct cmd_element * cmd );
 286
 287
 288 /**
 289  * 在进入节点函数中调用，用于进入节点
 290  * @param[in]   vty       vty
 291  * @param[in]   newnode   要进入的节点ID
 292  * @return      成功返回 VOS_OK,失败返回其他
 293  */
 294 LONG  vty_enter_node(struct vty *vty,enum node_type newnode);
 295
 296
 297 /**
 298  * 在进入节点函数中调用，用于自定义要进入节点的命令行提示符，
 299  * 调用vty_enter_node后调用
 300  * @param[in]   vty       vty
 301  * @param[in]   cpPrompt  提示符
 302  */
 303 VOID vty_set_prompt( struct vty * vty, CHAR cpPrompt[VTY_CMD_PROMPT_MAX] );
 304
 305
 306
 307
 308 /**
 309  * Completion match types. 匹配度，数值越大匹配度越高,命令行模块内部使用无需关心
 310  */
 311 enum match_type
 312 {
 313     no_match,
 314     incomplete_match,
 315     ambiguous_match,
 316     extend_match,
 317     vararg_match,
 318     one_element_two_partly_match,
 319     partly_match,
 320     almost_exact_match,   /* exactmatch except last word */
 321     ipv4_prefix_match,
 322     ipv4_match,
 323     ipv6_prefix_match,
 324     ipv6_match,
 325
 326     aann_match,
 327     mac_match,
 328     slot_port_match,
 329     slot_subport_match,
 330
 331     time_match,
 332     range_match,
 333
 334     /*其余的匹配类型在此之前*/
 335     register_match,
 336
 337     exact_match
 338 };
 339
 340
 341 /** 自定义命令行参数解析函数  */
 342 typedef struct _cmd_notify_register_tag
 343 {
 344     CHAR *match_str ;                            ///<  匹配的格式，如<H.H.H>
 345     enum match_type (*pnotify_call) (CHAR *str); ///<  格式解析的回调函数，解析成功返回exact_match，解析失败返回no_match
 346     CHAR IsCapital ;                             ///<  是否包含大写字母 0 － 全小写； 1 － 含有大写字母
 347 }CMD_NOTIFY_REFISTER_S;
 348
 349 /**
 350  * 添加自定义命令行参数解析函数
 351  * @param[in]   pNotifyRegister   自定义解析函数信息
 352  * @return      成功返回 register_match,失败返回no_match
 353  */
 354 enum match_type cmd_rugular_register(CMD_NOTIFY_REFISTER_S * pNotifyRegister);
 355
 356 /**
 357  * 配置/获取 vty超时时间
 358  * @param[in ]   vty         vty
 359  * @param[in ]   newTime     新的超时时间，大于等于0时有效，0表示不会超时
 360  * @param[out]   oldTime     如果不为NULL 返回配置前的超时时间
 361  * @return      成功返回 VOS_OK，失败则返回其他
 362  */
 363 LONG vty_timeout_config ( struct vty * vty, LONG newTime, LONG *oldTime);
 364
 365
 366 /**
 367  * 要使用vty_very_big_out 函数必须先调用此初始化函数
 368  * @param[in ]   vty         vty
 369  */
 370 void vty_very_big_out_init ( struct vty *vty );
 371
 372 /**
 373  * 用于长字符串打印
 374  * @param[in]   vty     vty
 375  * @param[in]   format  格式字符串
 376  * @param[in]   ...     要输出的变量
 377  */
 378 int vty_very_big_out (struct vty *vty, const char *format, ...);
 379
 380
 381 #ifdef __cplusplus
 382 }
 383 #endif /* __cplusplus */
 384 #endif /* __VOS_CLI_H__ */