ns_cmdline.h

00001 /*
00002  * Copyright (c) 2016 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /**
00018  * \file ns_cmdline.h
00019  *
00020  * Command line library - mbedOS shell
00021  *
00022  * Usage example:
00023  *
00024  * \code
00025  * //simple print function
00026  * void myprint(const char* fmt, va_list ap){ vprintf(fmt, ap); }
00027  * // simple ready cb, which call next command to be execute
00028  * void cmd_ready_cb(int retcode) { cmd_next( retcode ); }
00029  *
00030  * // dummy command with some option
00031  * int cmd_dummy(int argc, char *argv[]){
00032  *  if( cmd_has_option(argc, argv, "o") ) {
00033  *    cmd_printf("This is o option");
00034  *  } else {
00035  *    return CMDLINE_RETCODE_INVALID_PARAMETERS;
00036  *  }
00037  *  return CMDLINE_RETCODE_SUCCESS;
00038  *}
00039  * // timer cb ( pseudo-timer-code )
00040  * void timer_ready_cb(void) {
00041  *   cmd_ready(CMDLINE_RETCODE_SUCCESS);
00042  * }
00043  * // long command, which need e.g. some events to finalize command execution
00044  * int cmd_long(int argc, char *argv[] ) {
00045      timer_start( 5000, timer_ready_cb );
00046  *   return CMDLINE_RETCODE_EXCUTING_CONTINUE;
00047  * }
00048  * void main(void) {
00049  *   cmd_init( &myprint );              // initialize cmdline with print function
00050  *   cmd_set_ready_cb( cmd_ready_cb );  // configure ready cb
00051  *   cmd_add("dummy", cmd_dummy, 0, 0); // add one dummy command
00052  *   cmd_add("long", cmd_long, 0, 0);   // add one dummy command
00053  *   //execute dummy and long commands
00054  *   cmd_exe( "dymmy;long" );
00055  * }
00056  * \endcode
00057  */
00058 #ifndef _CMDLINE_H_
00059 #define _CMDLINE_H_
00060 
00061 #ifdef __cplusplus
00062 extern "C" {
00063 #endif
00064 
00065 #include <stdarg.h>
00066 #include <stdint.h>
00067 #include <stddef.h>
00068 #include <stdbool.h>
00069 
00070 #define CMDLINE_RETCODE_COMMAND_BUSY            2   //!< Command Busy
00071 #define CMDLINE_RETCODE_EXCUTING_CONTINUE       1   //!< Execution continue in background
00072 #define CMDLINE_RETCODE_SUCCESS                 0   //!< Execution Success
00073 #define CMDLINE_RETCODE_FAIL                    -1  //!< Execution Fail
00074 #define CMDLINE_RETCODE_INVALID_PARAMETERS      -2  //!< Command parameters was incorrect
00075 #define CMDLINE_RETCODE_COMMAND_NOT_IMPLEMENTED -3  //!< Command not implemented
00076 #define CMDLINE_RETCODE_COMMAND_CB_MISSING      -4  //!< Command callback function missing
00077 #define CMDLINE_RETCODE_COMMAND_NOT_FOUND       -5  //!< Command not found
00078 
00079 /**
00080  * typedef for print functions
00081  */
00082 typedef void (cmd_print_t)(const char *, va_list);
00083 /**
00084  * Initialize cmdline class.
00085  * This is command line editor without any commands. Application
00086  * needs to add commands that should be enabled.
00087  * usage e.g.
00088  * \code
00089     cmd_init( &default_cmd_response_out );
00090  * \endcode
00091  * \param outf  console printing function (like vprintf)
00092  */
00093 void cmd_init(cmd_print_t *outf);
00094 /** Command ready function for __special__ cases.
00095  * This need to be call if command implementation return CMDLINE_RETCODE_EXECUTING_CONTINUE
00096  * because there is some background stuff ongoing before command is finally completed.
00097  * Normally there is some event, which call cmd_ready().
00098  * \param retcode return code for command
00099  */
00100 void cmd_ready(int retcode);
00101 /** typedef for ready cb function */
00102 typedef void (cmd_ready_cb_f)(int);
00103 /**
00104  * Configure cb which will be called after commands are executed
00105  * or cmd_ready is called
00106  * \param cb    callback function for command ready
00107  */
00108 void cmd_set_ready_cb(cmd_ready_cb_f *cb);
00109 /**
00110  * execute next command if any
00111  * \param retcode last command return value
00112  */
00113 void cmd_next(int retcode);
00114 /** Free cmd class */
00115 void cmd_free(void);
00116 /** Reset cmdline to default values
00117  *  detach external commands, delete all variables and aliases
00118  */
00119 void cmd_reset(void);
00120 /** Configure command history size (default 32)
00121  *  \param max  maximum history size
00122  *  max > 0 -> configure new value
00123  *  max = 0 -> just return current value
00124  *  \return current history max-size
00125  */
00126 uint8_t cmd_history_size(uint8_t max);
00127 /** command line print function
00128  *  This function should be used when user want to print something to the console
00129  *  \param fmt   console print function (like printf)
00130  */
00131 #if defined(__GNUC__) || defined(__CC_ARM)
00132 void cmd_printf(const char *fmt, ...)  __attribute__((__format__(__printf__, 1, 2)));
00133 #else
00134 void cmd_printf(const char *fmt, ...);
00135 #endif
00136 /** command line print function
00137  *  This function should be used when user want to print something to the console with vprintf functionality
00138  *  \param fmt  The format string is a character string, beginning and ending in its initial shift state, if any. The format string is composed of zero or more directives.
00139  *  \param ap   list of parameters needed by format string. This must correspond properly with the conversion specifier.
00140  */
00141 #if defined(__GNUC__) || defined(__CC_ARM)
00142 void cmd_vprintf(const char *fmt, va_list ap)  __attribute__((__format__(__printf__, 1, 0)));
00143 #else
00144 void cmd_vprintf(const char *fmt, va_list ap);
00145 #endif
00146 /** Reconfigure default cmdline out function (cmd_printf)
00147  *  \param outf  select console print function
00148  */
00149 void cmd_out_func(cmd_print_t *outf);
00150 /** Configure function, which will be called when Ctrl+A is pressed
00151  * \param sohf control function which called every time when user input control keys
00152  */
00153 void cmd_ctrl_func(void (*sohf)(uint8_t c));
00154 /**
00155  * Configure mutex wait function
00156  * By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.
00157  * This can be used to set a callback function that will be called before each cmd_printf call.
00158  * The specific implementation is up to the application developer, but simple mutex locking is assumed.
00159  */
00160 void cmd_mutex_wait_func(void (*mutex_wait_f)(void));
00161 /**
00162  * Configure mutex wait function
00163  * By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.
00164  * This can be used to set a callback function that will be called after each cmd_printf call.
00165  * The specific implementation is up to the application developer, but simple mutex locking is assumed.
00166  */
00167 void cmd_mutex_release_func(void (*mutex_release_f)(void));
00168 /**
00169  * Retrieve output mutex lock
00170  * This can be used to retrieve the output mutex when multiple cmd_printf/cmd_vprintf calls must be
00171  * guaranteed to be grouped together in a thread safe manner. Must be released by a following call to
00172  * cmd_mutex_unlock()
00173  * For example:
00174  * * \code
00175  * cmd_mutex_lock();
00176    for (i = 0; i < 10; i++) {
00177        cmd_printf("%02x ", i);
00178    }
00179    // without locking a print from another thread could happen here
00180    cmd_printf("\r\n);
00181    cmd_mutex_unlock();
00182  * \endcode
00183  * Exact behaviour depends on the implementation of the configured mutex,
00184  * but counting mutexes are required.
00185  */
00186 void cmd_mutex_lock(void);
00187 /**
00188  * Release output mutex lock
00189  * This can be used to release the output mutex once it has been retrieved with cmd_mutex_lock()
00190  * Exact behaviour depends on the implementation of the configured mutex,
00191  * but counting mutexes are required.
00192  */
00193 void cmd_mutex_unlock(void);
00194 /** Refresh output */
00195 void cmd_output(void);
00196 /** default cmd response function, use stdout
00197  *  \param fmt  The format string is a character string, beginning and ending in its initial shift state, if any. The format string is composed of zero or more directives.
00198  *  \param ap   list of parameters needed by format string. This must correspond properly with the conversion specifier.
00199  */
00200 void default_cmd_response_out(const char *fmt, va_list ap);
00201 /** Initialize screen */
00202 void cmd_init_screen(void);
00203 /** Get echo state
00204  * \return true if echo is on otherwise false
00205  */
00206 bool cmd_echo_state(void);
00207 /** Echo off */
00208 void cmd_echo_off(void);
00209 /** Echo on */
00210 void cmd_echo_on(void);
00211 /** Enter character to console.
00212  * insert key pressess to cmdline called from main loop of application
00213  * \param u_data char to be added to console
00214  */
00215 void cmd_char_input(int16_t u_data);
00216 /*
00217  * Set the passthrough mode callback function. In passthrough mode normal command input handling is skipped and any
00218  * received characters are passed to the passthrough callback function. Setting this to null will disable passthrough mode.
00219  * \param passthrough_fnc The passthrough callback function
00220  */
00221 typedef void (*input_passthrough_func_t)(uint8_t c);
00222 void cmd_input_passthrough_func(input_passthrough_func_t passthrough_fnc);
00223 
00224 /* Methods used for adding and handling of commands and aliases
00225  */
00226 
00227 /** Callback called when your command is run.
00228  * \param argc argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
00229  * \param argv argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
00230  */
00231 typedef int (cmd_run_cb)(int argc, char *argv[]);
00232 /** Add command to intepreter
00233  * \param name      command string
00234  * \param callback  This function is called when command line start executing
00235  * \param info      Command short description which is visible in help command, or null if not in use
00236  * \param man       Help page for this command. This is shown when executing command with invalid parameters or command with --help parameter. Can be null if not in use.
00237  */
00238 void cmd_add(const char *name, cmd_run_cb *callback, const char *info, const char *man);
00239 
00240 /** delete command from intepreter
00241  *  \param name command to be delete
00242  */
00243 void cmd_delete(const char *name);
00244 /** Command executer.
00245  * Command executer, which split&push command(s) to the buffer and
00246  * start executing commands in cmd tasklet.
00247  * if not, execute command directly.
00248  * If command implementation returns CMDLINE_RETCODE_EXCUTING_CONTINUE,
00249  * executor will wait for cmd_ready() before continue to next command.
00250  * \param str  command string, e.g. "help"
00251  */
00252 void cmd_exe(char *str);
00253 /** Add alias to interpreter.
00254  * Aliases are replaced with values before executing a command. All aliases must be started from beginning of line.
00255  * null or empty value deletes alias.
00256  * \code
00257    cmd_alias_add("print", "echo");
00258    cmd_exe("print \"hello world!\""); // this is now same as "echo \"hello world!\"" .
00259  * \endcode
00260  * \param alias     alias name
00261  * \param value     value for alias. Values can be any visible ASCII -characters.
00262  */
00263 void cmd_alias_add(const char *alias, const char *value);
00264 /** Add Variable to interpreter.
00265  * Variables are replaced with values before executing a command.
00266  * To use variables from cli, use dollar ($) -character so that interpreter knows user want to use variable in that place.
00267  * null or empty value deletes variable.
00268  * \code
00269    cmd_variable_add("world", "hello world!");
00270    cmd_exe("echo $world"); // this is now same as echo "hello world!" .
00271  * \endcode
00272  * \param variable  Variable name, which will be replaced in interpreter.
00273  * \param value     Value for variable. Values can contains white spaces and '"' or '"' characters.
00274  */
00275 void cmd_variable_add(char *variable, char *value);
00276 /**
00277  * Add integer variable to interpreter.
00278  * Variables are replaced with values before executing a command.
00279  * \code
00280    cmd_variable_add_int("world", 2);
00281    cmd_exe("echo $world"); // this is now same as 'echo 2' .
00282  * \endcode
00283  * \param variable  Variable name, which will be replaced in interpreter.
00284  * \param value     Value for variable
00285 
00286  */
00287 void cmd_variable_add_int(char *variable, int value);
00288 /**
00289  * Request screen size from host
00290  * Response are stored to variables:
00291  * COLUMNS and LINES - as integer values.
00292  * Note: Require terminal that handle request codes, like screen.
00293  */
00294 void cmd_request_screen_size(void);
00295 
00296 
00297 /** find command parameter index by key.
00298  * e.g.
00299  * \code
00300       int main(void){
00301             //..init cmd..
00302             //..
00303             cmd_exe("mycmd enable")
00304       }
00305       int mycmd_command(int argc, char *argv[]) {
00306         bool found = cmd_parameter_index( argc, argv, "enable" ) > 0;
00307       }
00308  * \endcode
00309  * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
00310  * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
00311  * \param key   option key, which index you want to find out.
00312  * \return index where parameter was or -1 when not found
00313  */
00314 int cmd_parameter_index(int argc, char *argv[], const char *key);
00315 /** check if command option is present.
00316  * e.g. cmd: "mycmd -c"
00317  * \code
00318  *    bool on = cmd_has_option( argc, argv, "p" );
00319  * \endcode
00320  * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
00321  * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
00322  * \param key   option key to be find
00323  * \return true if option found otherwise false
00324  */
00325 bool cmd_has_option(int argc, char *argv[], const char *key);
00326 /** find command parameter by key.
00327  * if exists, return true, otherwise false.
00328  * e.g. cmd: "mycmd enable 1"
00329  * \code
00330   int mycmd_command(int argc, char *argv[]) {
00331         bool value;
00332         bool found = cmd_parameter_bool( argc, argv, "mykey", &value );
00333         if( found ) return CMDLINE_RETCODE_SUCCESS;
00334         else return CMDLINE_RETCODE_FAIL;
00335     }
00336  * \endcode
00337  * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
00338  * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
00339  * \param key   parameter key to be find
00340  * \param value parameter value to be fetch, if key not found value are untouched. "1" and "on" and "true" and "enable" and "allow" are True -value, all others false.
00341  * \return true if parameter key and value found otherwise false
00342  */
00343 bool cmd_parameter_bool(int argc, char *argv[], const char *key, bool *value);
00344 /** find command parameter by key and return value (next parameter).
00345  * if exists, return parameter pointer, otherwise null.
00346  * e.g. cmd: "mycmd mykey myvalue"
00347  * \code
00348     int mycmd_command(int argc, char *argv[]) {
00349         char *value;
00350         bool found = cmd_parameter_val( argc, argv, "mykey", &value );
00351         if( found ) return CMDLINE_RETCODE_SUCCESS;
00352         else return CMDLINE_RETCODE_FAIL;
00353     }
00354  * \endcode
00355  * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
00356  * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
00357  * \param key   parameter key to be find
00358  * \param value pointer to pointer, which will point to cli input data when key and value found. if key or value not found this parameter are untouched.
00359  * \return true if parameter key and value found otherwise false
00360  */
00361 bool cmd_parameter_val(int argc, char *argv[], const char *key, char **value);
00362 /** find command parameter by key and return value (next parameter) in integer. Only whitespaces are allowed in addition to the float to be read.
00363  * e.g. cmd: "mycmd mykey myvalue"
00364  * \code
00365      int32_t value;
00366      cmd_parameter_int( argc, argv, "key", &value );
00367  * \endcode
00368  * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the item 0 in the list argv is a string to name of command.
00369  * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
00370  * \param key   parameter key to be found
00371  * \param value A pointer to a variable where to write the converted number. If value cannot be converted, it is not touched.
00372  * \return true if parameter key and an integer is found, otherwise return false
00373  */
00374 bool cmd_parameter_int(int argc, char *argv[], const char *key, int32_t *value);
00375 /** find command parameter by key and return value (next parameter) in float. Only whitespaces are allowed in addition to the float to be read.
00376  * e.g. cmd: "mycmd mykey myvalue"
00377  * \code
00378      float value;
00379      cmd_parameter_float( argc, argv, "key", &value );
00380  * \endcode
00381  * \param argc  argc is the count of arguments given in argv pointer list. values begin from 1 and this means that the item 0 in the list argv is a string to name of command.
00382  * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
00383  * \param key   parameter key to be found
00384  * \param value A pointer to a variable where to write the converted number. If value cannot be converted, it is not touched.
00385  * \return true if parameter key and a float found, otherwise return false
00386  */
00387 bool cmd_parameter_float(int argc, char *argv[], const char *key, float *value);
00388 /** Get last command line parameter as string.
00389  * e.g.
00390  *     cmd: "mycmd hello world"
00391  *     cmd_parameter_last -> "world"
00392  *     cmd: "mycmd"
00393  *     cmd_parameter_last() -> NULL
00394  * \code
00395     cmd_parameter_last(argc, argv)
00396  * \endcode
00397  * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
00398  * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
00399  * \return pointer to last parameter or NULL when there is no any parameters.
00400  */
00401 char *cmd_parameter_last(int argc, char *argv[]);
00402 
00403 /** find command parameter by key and return value (next parameter) in int64.
00404  * e.g. cmd: "mycmd mykey myvalue"
00405  * \code
00406      uint32_t i;
00407      cmd_parameter_timestamp( argc, argv, "mykey", &i );
00408  * \endcode
00409  *
00410  * Supports following formats:
00411  *  number -> direct conversion
00412  *  11:22:33:44:55:66:77:88 -> converts to number
00413  *  seconds,tics -> converts thread type timestamp to int64
00414  *
00415  * \param argc  argc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
00416  * \param argv  is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
00417  * \param key   parameter key to be find
00418  * \param value parameter value to be fetch, if key not found value are untouched.
00419  * \return true if parameter key and value found otherwise false
00420  */
00421 bool cmd_parameter_timestamp(int argc, char *argv[], const char *key, int64_t *value);
00422 
00423 #ifdef __cplusplus
00424 }
00425 #endif
00426 #endif /*_CMDLINE_H_*/