Ignore:
Timestamp:
Nov 23, 2012 10:30:55 AM (12 years ago)
Author:
riza
Message:

Re #1098: Additional implementation to command parsing, telnet front end, console front end

File:
1 edited

Legend:

Unmodified
Added
Removed

  • pjproject/branches/projects/cli/pjlib-util/include/pjlib-util/cli.h

    r3231 r4299  
    3434 * @defgroup PJLIB_UTIL_CLI Command Line Interface Framework 
    3535 * @{ 
    36  * 
     36 * A CLI framework features an interface for defining command specification,  
     37 * parsing, and executing a command.  
     38 * It also features an interface to communicate with various front-ends,  
     39 * such as console, telnet. 
     40 * 
     41\verbatim 
     42| vid help                  Show this help screen                             | 
     43| vid enable|disable        Enable or disable video in next offer/answer      | 
     44| vid call add              Add video stream for current call                 | 
     45| vid call cap N ID         Set capture dev ID for stream #N in current call  | 
     46| disable_codec g711|g722   Show this help screen                             | 
     47<CMD name='vid' id='0' desc=""> 
     48       <CMD name='help' id='0' desc='' /> 
     49       <CMD name='enable' id='0' desc='' /> 
     50       <CMD name='disable' id='0' desc='' /> 
     51       <CMD name='call' id='0' desc='' > 
     52                <CMD name='add' id='101' desc='...' /> 
     53                <CMD name='cap' id='102' desc='...' > 
     54                   <ARG name='streamno' type='int' desc='...' id='1'/> 
     55                   <ARG name='devid' type='int' optional='1' id='2'/> 
     56                </CMD> 
     57       </CMD> 
     58</CMD> 
     59<CMD name='disable_codec' id=0 desc=""> 
     60        <ARG name='codec_list' type='choice' id='3'> 
     61            <CHOICE value='g711'/> 
     62            <CHOICE value='g722'/> 
     63        </ARG> 
     64</CMD> 
     65\endverbatim  
    3766 */ 
    3867 
    … …  
    5079 
    5180/** 
    52  * Reserved command id constants. 
    53  */ 
    54 typedef enum pj_cli_std_cmd_id 
    55 { 
    56     /** 
    57      * Constant to indicate an invalid command id. 
    58      */ 
    59     PJ_CLI_INVALID_CMD_ID = -1, 
    60  
    61     /** 
    62      * A special command id to indicate that a command id denotes 
    63      * a command group. 
    64      */ 
    65     PJ_CLI_CMD_ID_GROUP = -2 
    66  
    67 } pj_cli_std_cmd_id; 
    68  
    69  
    70 /** 
    7181 * This describes the parameters to be specified when creating a CLI 
    7282 * application with pj_cli_create(). Application MUST initialize this 
    … …  
    96106} pj_cli_cfg; 
    97107 
    98  
    99 /** 
    100  * This describes the type of an argument (pj_cli_arg_spec). 
    101  */ 
    102 typedef enum pj_cli_arg_type 
    103 { 
    104     /** 
    105      * Unformatted string. 
    106      */ 
    107     PJ_CLI_ARG_TEXT, 
    108  
    109     /** 
    110      * An integral number. 
    111      */ 
    112     PJ_CLI_ARG_INT 
    113  
    114 } pj_cli_arg_type; 
    115  
    116 /** 
    117  * This structure describe the specification of a command argument. 
    118  */ 
    119 typedef struct pj_cli_arg_spec 
    120 { 
    121     /** 
    122      * Argument name. 
    123      */ 
    124     pj_str_t name; 
    125  
    126     /** 
    127      * Helpful description of the argument. This text will be used when 
    128      * displaying help texts for the command/argument. 
    129      */ 
    130     pj_str_t desc; 
    131  
    132     /** 
    133      * Argument type, which will be used for rendering the argument and 
    134      * to perform basic validation against an input value. 
    135      */ 
    136     pj_cli_arg_type type; 
    137  
    138 } pj_cli_arg_spec; 
    139  
     108/** 
     109 * Type of argument id. 
     110 */ 
     111typedef int pj_cli_arg_id; 
    140112 
    141113/** 
    … …  
    153125 */ 
    154126typedef struct pj_cli_front_end pj_cli_front_end; 
     127 
     128/** 
     129 * Forward declaration for CLI argument spec structure. 
     130 */ 
     131typedef struct pj_cli_arg_spec pj_cli_arg_spec; 
    155132 
    156133/** 
    … …  
    173150} pj_cli_cmd_val; 
    174151 
    175  
    176  
    177 /** 
    178  * This specifies the callback type for command handlers, which will be 
    179  * executed when the specified command is invoked. 
    180  * 
    181  * @param sess      The CLI session where the command is invoked. 
    182  * @param cmd_val   The command that is specified by the user. 
    183  * 
    184  * @return          Return the status of the command execution. 
    185  */ 
    186 typedef pj_status_t (*pj_cli_cmd_handler)(pj_cli_cmd_val *cval); 
    187  
    188 /** 
    189  * This structure describes the full specification of a CLI command. A CLI 
    190  * command mainly consists of the name of the command, zero or more arguments, 
    191  * and a callback function to be called to execute the command. 
    192  * 
    193  * Application can create this specification by forming an XML document and 
    194  * calling pj_cli_create_cmd_from_xml() to instantiate the spec. A sample XML 
    195  * document containing a command spec is as follows: 
    196  * 
    197  \verbatim 
    198   <CMD name='makecall' id='101' sc='m,mc' desc='Make outgoing call'> 
    199       <ARGS> 
    200           <ARG name='target' type='text' desc='The destination'/> 
    201       </ARGS> 
    202   </CMD> 
    203  \endverbatim 
    204  
    205  */ 
    206 struct pj_cli_cmd_spec 
     152/** 
     153 * This structure contains the hints information for the end user.  
     154 * This structure could contain either command or argument information. 
     155 * The front-end will format the information and present it to the user. 
     156 */ 
     157typedef struct pj_cli_hint_info 
    207158{ 
    208159    /** 
    209      * To make list of child cmds. 
    210      */ 
    211     PJ_DECL_LIST_MEMBER(struct pj_cli_cmd_spec); 
    212  
    213     /** 
    214      * Command ID assigned to this command by the application during command 
    215      * creation. If this value is PJ_CLI_CMD_ID_GROUP (-2), then this is 
    216      * a command group and it can't be executed. 
    217      */ 
    218     pj_cli_cmd_id id; 
    219  
    220     /** 
    221      * The command name. 
     160     * The hint value. 
    222161     */ 
    223162    pj_str_t name; 
    224163 
    225164    /** 
    226      * The full description of the command. 
     165     * The hint type. 
     166     */ 
     167    pj_str_t type; 
     168 
     169    /** 
     170     * Helpful description of the hint value.  
    227171     */ 
    228172    pj_str_t desc; 
    229173 
    230     /** 
    231      * Number of optional shortcuts 
    232      */ 
    233     unsigned sc_cnt; 
    234  
    235     /** 
    236      * Optional array of shortcuts, if any. Shortcut is a short name version 
    237      * of the command. If the command doesn't have any shortcuts, this 
    238      * will be initialized to NULL. 
    239      */ 
    240     pj_str_t *sc; 
    241  
    242     /** 
    243      * The command handler, to be executed when a command matching this command 
    244      * specification is invoked by the end user. The value may be NULL if this 
    245      * is a command group. 
    246      */ 
    247     pj_cli_cmd_handler handler; 
    248  
    249     /** 
    250      * Number of arguments. 
    251      */ 
    252     unsigned arg_cnt; 
    253  
    254     /** 
    255      * Array of arguments. 
    256      */ 
    257     pj_cli_arg_spec *arg; 
    258  
    259     /** 
    260      * Child commands, if any. A command will only have subcommands if it is 
    261      * a group. If the command doesn't have subcommands, this field will be 
    262      * initialized with NULL. 
    263      */ 
    264     pj_cli_cmd_spec *sub_cmd; 
    265 }; 
    266  
    267  
    268 /** 
    269  * This contains extra parameters to be specified when calling pj_cli_exec(). 
     174} pj_cli_hint_info; 
     175 
     176/** 
     177 * This structure contains extra information returned by pj_cli_sess_exec()/ 
     178 * pj_cli_sess_parse(). 
    270179 * Upon return from the function, various other fields in this structure will 
    271180 * be set by the function. 
    272  * 
    273  * Application must call pj_cli_exec_info_default() to initialize this 
    274  * structure with its default values. 
    275181 */ 
    276182typedef struct pj_cli_exec_info 
    … …  
    296202 
    297203    /** 
    298      * If pj_cli_exec() fails because an argument is missing (the function 
    299      * returned PJ_CLI_EMISSINGARG error), this field will be set to the 
    300      * index of the missing argument. This is useful to give more helpful 
    301      * error info to the end user, or to facilitate a more interactive 
    302      * input display. 
    303      */ 
    304     int arg_idx; 
     204     * The number of hint elements 
     205     **/ 
     206    unsigned hint_cnt; 
     207 
     208    /** 
     209     * If pj_cli_sess_parse() fails because of a missing argument or ambigous  
     210     * command/argument, the function returned PJ_CLI_EMISSINGARG or  
     211     * PJ_CLI_EAMBIGUOUS error.  
     212     * This field will contain the hint information. This is useful to give  
     213     * helpful information to the end_user. 
     214     */ 
     215    pj_cli_hint_info hint[PJ_CLI_MAX_HINTS]; 
    305216 
    306217} pj_cli_exec_info; 
    307218 
     219/** 
     220 * This structure contains the information returned from the dynamic  
     221 * argument callback. 
     222 */ 
     223typedef struct pj_cli_arg_choice_val 
     224{ 
     225    /** 
     226     * The argument choice value 
     227     */ 
     228    pj_str_t value; 
     229 
     230    /** 
     231     * Helpful description of the choice value. This text will be used when 
     232     * displaying the help texts for the choice value 
     233     */ 
     234    pj_str_t desc; 
     235 
     236} pj_cli_arg_choice_val; 
     237 
     238/** 
     239 * This structure contains the parameters for pj_cli_arg_get_dyn_choice_val 
     240 */ 
     241typedef struct pj_cli_dyn_choice_param 
     242{ 
     243    /** 
     244     * The session on which the command was executed on. 
     245     */ 
     246    pj_cli_sess *sess; 
     247 
     248    /** 
     249     * The command being processed. 
     250     */ 
     251    pj_cli_cmd_spec *cmd; 
     252 
     253    /** 
     254     * The argument id. 
     255     */ 
     256    pj_cli_arg_id arg_id; 
     257 
     258    /** 
     259     * The maximum number of values that the choice can hold. 
     260     */ 
     261    unsigned max_cnt; 
     262 
     263    /** 
     264     * The pool to allocate memory from. 
     265     */ 
     266    pj_pool_t *pool; 
     267 
     268    /** 
     269     * The choice values count. 
     270     */ 
     271    unsigned cnt; 
     272 
     273    /** 
     274     * Array containing the valid choice values. 
     275     */ 
     276    pj_cli_arg_choice_val choice[PJ_CLI_MAX_CHOICE_VAL]; 
     277} pj_cli_dyn_choice_param; 
     278 
     279/** 
     280 * This specifies the callback type for argument handlers, which will be 
     281 * called to get the valid values of the choice type arguments. 
     282 */ 
     283typedef void (*pj_cli_arg_get_dyn_choice_val) (pj_cli_dyn_choice_param *param); 
     284 
     285/** 
     286 * This specifies the function to get the id of the specified command 
     287 *  
     288 * @param cmd           The specified command. 
     289 * 
     290 * @return              The command id 
     291 */ 
     292PJ_DECL(pj_cli_cmd_id) pj_cli_get_cmd_id(const pj_cli_cmd_spec *cmd); 
     293 
     294/** 
     295 * This specifies the callback type for command handlers, which will be 
     296 * executed when the specified command is invoked. 
     297 * 
     298 * @param cmd_val   The command that is specified by the user. 
     299 * 
     300 * @return          Return the status of the command execution. 
     301 */ 
     302typedef pj_status_t (*pj_cli_cmd_handler)(pj_cli_cmd_val *cval); 
    308303 
    309304/** 
    … …  
    313308 */ 
    314309PJ_DECL(void) pj_cli_cfg_default(pj_cli_cfg *param); 
    315  
    316 /** 
    317  * Initialize pj_cli_exec_info with its default values. 
    318  * 
    319  * @param param         The param to be initialized. 
    320  */ 
    321 PJ_DECL(void) pj_cli_exec_info_default(pj_cli_exec_info *param); 
    322310 
    323311/** 
    … …  
    336324 
    337325/** 
     326 * Write a log message to the specific CLI session.  
     327 * 
     328 * @param sess          The CLI active session. 
     329 * @param buffer        The message itself. 
     330 * @param len           Length of this message. 
     331 */ 
     332PJ_DECL(void) pj_cli_sess_write_msg(pj_cli_sess *sess,                                
     333                                    const char *buffer, 
     334                                    int len); 
     335 
     336/** 
    338337 * Create a new CLI application instance. 
    339338 * 
    … …  
    345344PJ_DECL(pj_status_t) pj_cli_create(pj_cli_cfg *cfg, 
    346345                                   pj_cli_t **p_cli); 
    347  
    348346/** 
    349347 * Get the internal parameter of the CLI instance. 
    … …  
    354352 */ 
    355353PJ_DECL(pj_cli_cfg*) pj_cli_get_param(pj_cli_t *cli); 
    356  
    357354 
    358355/** 
    … …  
    361358 * application. 
    362359 * 
    363  * See also pj_cli_end_session() to end a session instead of quitting the 
     360 * See also pj_cli_sess_end_session() to end a session instead of quitting the 
    364361 * whole application. 
    365362 * 
    … …  
    371368PJ_DECL(void) pj_cli_quit(pj_cli_t *cli, pj_cli_sess *req, 
    372369                          pj_bool_t restart); 
    373  
    374370/** 
    375371 * Check if application shutdown or restart has been requested. 
    … …  
    380376 */ 
    381377PJ_DECL(pj_bool_t) pj_cli_is_quitting(pj_cli_t *cli); 
    382  
    383378 
    384379/** 
    … …  
    392387PJ_DECL(pj_bool_t) pj_cli_is_restarting(pj_cli_t *cli); 
    393388 
    394  
    395389/** 
    396390 * Destroy a CLI application instance. This would also close all sessions 
    … …  
    401395PJ_DECL(void) pj_cli_destroy(pj_cli_t *cli); 
    402396 
    403  
    404397/** 
    405398 * End the specified session, and destroy it to release all resources used 
    … …  
    410403 * @param sess          The CLI session to be destroyed. 
    411404 */ 
    412 PJ_DECL(void) pj_cli_end_session(pj_cli_sess *sess); 
     405PJ_DECL(void) pj_cli_sess_end_session(pj_cli_sess *sess); 
    413406 
    414407/** 
    … …  
    435428 * @param p_cmd         Optional pointer to store the newly created 
    436429 *                      specification. 
     430 * @param get_choice    Function handler for the argument. Specify this for  
     431 *                      dynamic choice type arguments. 
    437432 * 
    438433 * @return              PJ_SUCCESS on success, or the appropriate error code. 
    … …  
    442437                                             const pj_str_t *xml, 
    443438                                             pj_cli_cmd_handler handler, 
    444                                              pj_cli_cmd_spec *p_cmd); 
     439                                             pj_cli_cmd_spec **p_cmd,  
     440                                             pj_cli_arg_get_dyn_choice_val get_choice); 
     441/** 
     442 * Initialize pj_cli_exec_info with its default values. 
     443 * 
     444 * @param param         The param to be initialized. 
     445 */ 
     446PJ_DECL(void) pj_cli_exec_info_default(pj_cli_exec_info *param); 
    445447 
    446448/** 
    … …  
    465467 * @param cmdline       The command line string to be parsed. 
    466468 * @param val           Structure to store the parsing result. 
     469 * @param pool          The pool to allocate memory from. 
    467470 * @param info          Additional info to be returned regarding the parsing. 
    468471 * 
    … …  
    472475 *                        - PJ_EINVAL: invalid parameter to this function. 
    473476 *                        - PJ_ENOTFOUND: command is not found. 
     477 *                        - PJ_CLI_EAMBIGUOUS: command/argument is ambiguous. 
    474478 *                        - PJ_CLI_EMISSINGARG: missing argument. 
    475479 *                        - PJ_CLI_EINVARG: invalid command argument. 
    … …  
    478482 *                            application to end it's main loop. 
    479483 */ 
    480 PJ_DECL(pj_status_t) pj_cli_parse(pj_cli_sess *sess, 
    481                                   char *cmdline, 
    482                                   pj_cli_cmd_val *val, 
    483                                   pj_cli_exec_info *info); 
     484PJ_DECL(pj_status_t) pj_cli_sess_parse(pj_cli_sess *sess, 
     485                                       char *cmdline, 
     486                                       pj_cli_cmd_val *val, 
     487                                       pj_pool_t *pool, 
     488                                       pj_cli_exec_info *info); 
    484489 
    485490/** 
    … …  
    487492 * the appropriate command and verify whether the string matches the command 
    488493 * specifications. If matches, the command will be executed, and the return 
    489  * value of the command will be set in the \a cmd_ret field of the \a eparam 
     494 * value of the command will be set in the \a cmd_ret field of the \a info 
    490495 * argument, if specified. 
    491496 * 
    492  * Please also see pj_cli_parse() for more info regarding the cmdline format. 
     497 * Please also see pj_cli_sess_parse() for more info regarding the cmdline  
     498 * format. 
    493499 * 
    494500 * @param sess          The CLI session. 
    495  * @param cmdline       The command line string to be executed. See the 
    496  *                      description of pj_cli_parse() API for more info 
    497  *                      regarding the cmdline format. 
     501 * @param cmdline       The command line string to be executed.  
     502 * @param pool          The pool to allocate memory from. 
    498503 * @param info          Optional pointer to receive additional information 
    499504 *                      related to the execution of the command (such as 
    … …  
    504509 *                      of the handler itself will be returned in \a info 
    505510 *                      argument, if specified). Please see the return value 
    506  *                      of pj_cli_parse() for possible return values. 
    507  */ 
    508 pj_status_t pj_cli_exec(pj_cli_sess *sess, 
    509                         char *cmdline, 
    510                         pj_cli_exec_info *info); 
    511  
     511 *                      of pj_cli_sess_parse() for possible return values. 
     512 */ 
     513PJ_DECL(pj_status_t) pj_cli_sess_exec(pj_cli_sess *sess, 
     514                                      char *cmdline, 
     515                                      pj_pool_t *pool, 
     516                                      pj_cli_exec_info *info); 
    512517 
    513518/** 
Note: See TracChangeset for help on using the changeset viewer.