Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
ns_cmdline.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016 ARM Limited. All rights reserved.
3  * SPDX-License-Identifier: Apache-2.0
4  * Licensed under the Apache License, Version 2.0 (the License); you may
5  * not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /**
18  * \file ns_cmdline.h
19  *
20  * Command line library - mbedOS shell
21  *
22  * Usage example:
23  *
24  * \code
25  * //simple print function
26  * void myprint(const char* fmt, va_list ap){ vprintf(fmt, ap); }
27  * // simple ready cb, which call next command to be execute
28  * void cmd_ready_cb(int retcode) { cmd_next( retcode ); }
29  *
30  * // dummy command with some option
31  * int cmd_dummy(int argc, char *argv[]){
32  * if( cmd_has_option(argc, argv, "o") ) {
33  * cmd_printf("This is o option");
34  * } else {
35  * return CMDLINE_RETCODE_INVALID_PARAMETERS;
36  * }
37  * return CMDLINE_RETCODE_SUCCESS;
38  *}
39  * // timer cb ( pseudo-timer-code )
40  * void timer_ready_cb(void) {
41  * cmd_ready(CMDLINE_RETCODE_SUCCESS);
42  * }
43  * // long command, which need e.g. some events to finalize command execution
44  * int cmd_long(int argc, char *argv[] ) {
45  timer_start( 5000, timer_ready_cb );
46  * return CMDLINE_RETCODE_EXCUTING_CONTINUE;
47  * }
48  * void main(void) {
49  * cmd_init( &myprint ); // initialize cmdline with print function
50  * cmd_set_ready_cb( cmd_ready_cb ); // configure ready cb
51  * cmd_add("dummy", cmd_dummy, 0, 0); // add one dummy command
52  * cmd_add("long", cmd_long, 0, 0); // add one dummy command
53  * //execute dummy and long commands
54  * cmd_exe( "dymmy;long" );
55  * }
56  * \endcode
57  */
58 #ifndef _CMDLINE_H_
59 #define _CMDLINE_H_
60 
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64 
65 #include <stdarg.h>
66 #include <stdint.h>
67 #include <stddef.h>
68 #include <stdbool.h>
69 
70 #define CMDLINE_RETCODE_COMMAND_BUSY 2 //!< Command Busy
71 #define CMDLINE_RETCODE_EXCUTING_CONTINUE 1 //!< Execution continue in background
72 #define CMDLINE_RETCODE_SUCCESS 0 //!< Execution Success
73 #define CMDLINE_RETCODE_FAIL -1 //!< Execution Fail
74 #define CMDLINE_RETCODE_INVALID_PARAMETERS -2 //!< Command parameters was incorrect
75 #define CMDLINE_RETCODE_COMMAND_NOT_IMPLEMENTED -3 //!< Command not implemented
76 #define CMDLINE_RETCODE_COMMAND_CB_MISSING -4 //!< Command callback function missing
77 #define CMDLINE_RETCODE_COMMAND_NOT_FOUND -5 //!< Command not found
78 
79 /**
80  * typedef for print functions
81  */
82 typedef void (cmd_print_t)(const char *, va_list);
83 /**
84  * Initialize cmdline class.
85  * This is command line editor without any commands. Application
86  * needs to add commands that should be enabled.
87  * usage e.g.
88  * \code
89  cmd_init( &default_cmd_response_out );
90  * \endcode
91  * \param outf console printing function (like vprintf)
92  */
93 void cmd_init(cmd_print_t *outf);
94 /** Command ready function for __special__ cases.
95  * This need to be call if command implementation return CMDLINE_RETCODE_EXECUTING_CONTINUE
96  * because there is some background stuff ongoing before command is finally completed.
97  * Normally there is some event, which call cmd_ready().
98  * \param retcode return code for command
99  */
100 void cmd_ready(int retcode);
101 /** typedef for ready cb function */
102 typedef void (cmd_ready_cb_f)(int);
103 /**
104  * Configure cb which will be called after commands are executed
105  * or cmd_ready is called
106  * \param cb callback function for command ready
107  */
108 void cmd_set_ready_cb(cmd_ready_cb_f *cb);
109 /**
110  * execute next command if any
111  * \param retcode last command return value
112  */
113 void cmd_next(int retcode);
114 /** Free cmd class */
115 void cmd_free(void);
116 /** Reset cmdline to default values
117  * detach external commands, delete all variables and aliases
118  */
119 void cmd_reset(void);
120 /** Configure command history size (default 32)
121  * \param max maximum history size
122  * max > 0 -> configure new value
123  * max = 0 -> just return current value
124  * \return current history max-size
125  */
126 uint8_t cmd_history_size(uint8_t max);
127 /** command line print function
128  * This function should be used when user want to print something to the console
129  * \param fmt console print function (like printf)
130  */
131 #if defined(__GNUC__)
132 void cmd_printf(const char *fmt, ...) __attribute__((__format__(__printf__, 1, 2)));
133 #else
134 void cmd_printf(const char *fmt, ...);
135 #endif
136 /** command line print function
137  * This function should be used when user want to print something to the console with vprintf functionality
138  * \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.
139  * \param ap list of parameters needed by format string. This must correspond properly with the conversion specifier.
140  */
141 #if defined(__GNUC__)
142 void cmd_vprintf(const char *fmt, va_list ap) __attribute__((__format__(__printf__, 1, 0)));
143 #else
144 void cmd_vprintf(const char *fmt, va_list ap);
145 #endif
146 /** Reconfigure default cmdline out function (cmd_printf)
147  * \param outf select console print function
148  */
149 void cmd_out_func(cmd_print_t *outf);
150 /** Configure function, which will be called when Ctrl+A is pressed
151  * \param sohf control function which called every time when user input control keys
152  */
153 void cmd_ctrl_func(void (*sohf)(uint8_t c));
154 /**
155  * Configure mutex wait function
156  * By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.
157  * This can be used to set a callback function that will be called before each cmd_printf call.
158  * The specific implementation is up to the application developer, but simple mutex locking is assumed.
159  */
160 void cmd_mutex_wait_func(void (*mutex_wait_f)(void));
161 /**
162  * Configure mutex wait function
163  * By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.
164  * This can be used to set a callback function that will be called after each cmd_printf call.
165  * The specific implementation is up to the application developer, but simple mutex locking is assumed.
166  */
167 void cmd_mutex_release_func(void (*mutex_release_f)(void));
168 /**
169  * Retrieve output mutex lock
170  * This can be used to retrieve the output mutex when multiple cmd_printf/cmd_vprintf calls must be
171  * guaranteed to be grouped together in a thread safe manner. Must be released by a following call to
172  * cmd_mutex_unlock()
173  * For example:
174  * * \code
175  * cmd_mutex_lock();
176  for (i = 0; i < 10; i++) {
177  cmd_printf("%02x ", i);
178  }
179  // without locking a print from another thread could happen here
180  cmd_printf("\r\n);
181  cmd_mutex_unlock();
182  * \endcode
183  * Exact behaviour depends on the implementation of the configured mutex,
184  * but counting mutexes are required.
185  */
186 void cmd_mutex_lock(void);
187 /**
188  * Release output mutex lock
189  * This can be used to release the output mutex once it has been retrieved with cmd_mutex_lock()
190  * Exact behaviour depends on the implementation of the configured mutex,
191  * but counting mutexes are required.
192  */
193 void cmd_mutex_unlock(void);
194 /** Refresh output */
195 void cmd_output(void);
196 /** default cmd response function, use stdout
197  * \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.
198  * \param ap list of parameters needed by format string. This must correspond properly with the conversion specifier.
199  */
200 void default_cmd_response_out(const char *fmt, va_list ap);
201 /** Initialize screen */
202 void cmd_init_screen(void);
203 /** Get echo state
204  * \return true if echo is on otherwise false
205  */
206 bool cmd_echo_state(void);
207 /** Echo off */
208 void cmd_echo_off(void);
209 /** Echo on */
210 void cmd_echo_on(void);
211 /** Enter character to console.
212  * insert key pressess to cmdline called from main loop of application
213  * \param u_data char to be added to console
214  */
215 void cmd_char_input(int16_t u_data);
216 /*
217  * Set the passthrough mode callback function. In passthrough mode normal command input handling is skipped and any
218  * received characters are passed to the passthrough callback function. Setting this to null will disable passthrough mode.
219  * \param passthrough_fnc The passthrough callback function
220  */
221 typedef void (*input_passthrough_func_t)(uint8_t c);
222 void cmd_input_passthrough_func(input_passthrough_func_t passthrough_fnc);
223 
224 /* Methods used for adding and handling of commands and aliases
225  */
226 
227 /** Callback called when your command is run.
228  * \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.
229  * \param argv argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
230  */
231 typedef int (cmd_run_cb)(int argc, char *argv[]);
232 /** Add command to intepreter
233  * \param name command string
234  * \param callback This function is called when command line start executing
235  * \param info Command short description which is visible in help command, or null if not in use
236  * \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.
237  */
238 void cmd_add(const char *name, cmd_run_cb *callback, const char *info, const char *man);
239 
240 /** delete command from intepreter
241  * \param name command to be delete
242  */
243 void cmd_delete(const char *name);
244 /** Command executer.
245  * Command executer, which split&push command(s) to the buffer and
246  * start executing commands in cmd tasklet.
247  * if not, execute command directly.
248  * If command implementation returns CMDLINE_RETCODE_EXCUTING_CONTINUE,
249  * executor will wait for cmd_ready() before continue to next command.
250  * \param str command string, e.g. "help"
251  */
252 void cmd_exe(char *str);
253 /** Add alias to interpreter.
254  * Aliases are replaced with values before executing a command. All aliases must be started from beginning of line.
255  * null or empty value deletes alias.
256  * \code
257  cmd_alias_add("print", "echo");
258  cmd_exe("print \"hello world!\""); // this is now same as "echo \"hello world!\"" .
259  * \endcode
260  * \param alias alias name
261  * \param value value for alias. Values can be any visible ASCII -characters.
262  */
263 void cmd_alias_add(const char *alias, const char *value);
264 /** Add Variable to interpreter.
265  * Variables are replaced with values before executing a command.
266  * To use variables from cli, use dollar ($) -character so that interpreter knows user want to use variable in that place.
267  * null or empty value deletes variable.
268  * \code
269  cmd_variable_add("world", "hello world!");
270  cmd_exe("echo $world"); // this is now same as echo "hello world!" .
271  * \endcode
272  * \param variable Variable name, which will be replaced in interpreter.
273  * \param value Value for variable. Values can contains white spaces and '"' or '"' characters.
274  */
275 void cmd_variable_add(char *variable, char *value);
276 /**
277  * Add integer variable to interpreter.
278  * Variables are replaced with values before executing a command.
279  * \code
280  cmd_variable_add_int("world", 2);
281  cmd_exe("echo $world"); // this is now same as 'echo 2' .
282  * \endcode
283  * \param variable Variable name, which will be replaced in interpreter.
284  * \param value Value for variable
285 
286  */
287 void cmd_variable_add_int(char *variable, int value);
288 /**
289  * Request screen size from host
290  * Response are stored to variables:
291  * COLUMNS and LINES - as integer values.
292  * Note: Require terminal that handle request codes, like screen.
293  */
294 void cmd_request_screen_size(void);
295 
296 /** find command parameter index by key.
297  * e.g.
298  * \code
299  int main(void){
300  //..init cmd..
301  //..
302  cmd_exe("mycmd enable")
303  }
304  int mycmd_command(int argc, char *argv[]) {
305  bool found = cmd_parameter_index( argc, argv, "enable" ) > 0;
306  }
307  * \endcode
308  * \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.
309  * \param argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
310  * \param key option key, which index you want to find out.
311  * \return index where parameter was or -1 when not found
312  */
313 int cmd_parameter_index(int argc, char *argv[], const char *key);
314 /** check if command option is present.
315  * e.g. cmd: "mycmd -c"
316  * \code
317  * bool on = cmd_has_option( argc, argv, "p" );
318  * \endcode
319  * \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.
320  * \param argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
321  * \param key option key to be find
322  * \return true if option found otherwise false
323  */
324 bool cmd_has_option(int argc, char *argv[], const char *key);
325 /** find command parameter by key.
326  * if exists, return true, otherwise false.
327  * e.g. cmd: "mycmd enable 1"
328  * \code
329  int mycmd_command(int argc, char *argv[]) {
330  bool value;
331  bool found = cmd_parameter_bool( argc, argv, "mykey", &value );
332  if( found ) return CMDLINE_RETCODE_SUCCESS;
333  else return CMDLINE_RETCODE_FAIL;
334  }
335  * \endcode
336  * \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.
337  * \param argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
338  * \param key parameter key to be find
339  * \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.
340  * \return true if parameter key and value found otherwise false
341  */
342 bool cmd_parameter_bool(int argc, char *argv[], const char *key, bool *value);
343 /** find command parameter by key and return value (next parameter).
344  * if exists, return parameter pointer, otherwise null.
345  * e.g. cmd: "mycmd mykey myvalue"
346  * \code
347  int mycmd_command(int argc, char *argv[]) {
348  char *value;
349  bool found = cmd_parameter_val( argc, argv, "mykey", &value );
350  if( found ) return CMDLINE_RETCODE_SUCCESS;
351  else return CMDLINE_RETCODE_FAIL;
352  }
353  * \endcode
354  * \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.
355  * \param argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
356  * \param key parameter key to be find
357  * \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.
358  * \return true if parameter key and value found otherwise false
359  */
360 bool cmd_parameter_val(int argc, char *argv[], const char *key, char **value);
361 /** find command parameter by key and return value (next parameter) in integer. Only whitespaces are allowed in addition to the float to be read.
362  * e.g. cmd: "mycmd mykey myvalue"
363  * \code
364  int32_t value;
365  cmd_parameter_int( argc, argv, "key", &value );
366  * \endcode
367  * \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.
368  * \param argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
369  * \param key parameter key to be found
370  * \param value A pointer to a variable where to write the converted number. If value cannot be converted, it is not touched.
371  * \return true if parameter key and an integer is found, otherwise return false
372  */
373 bool cmd_parameter_int(int argc, char *argv[], const char *key, int32_t *value);
374 /** find command parameter by key and return value (next parameter) in float. Only whitespaces are allowed in addition to the float to be read.
375  * e.g. cmd: "mycmd mykey myvalue"
376  * \code
377  float value;
378  cmd_parameter_float( argc, argv, "key", &value );
379  * \endcode
380  * \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.
381  * \param argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
382  * \param key parameter key to be found
383  * \param value A pointer to a variable where to write the converted number. If value cannot be converted, it is not touched.
384  * \return true if parameter key and a float found, otherwise return false
385  */
386 bool cmd_parameter_float(int argc, char *argv[], const char *key, float *value);
387 /** Get last command line parameter as string.
388  * e.g.
389  * cmd: "mycmd hello world"
390  * cmd_parameter_last -> "world"
391  * cmd: "mycmd"
392  * cmd_parameter_last() -> NULL
393  * \code
394  cmd_parameter_last(argc, argv)
395  * \endcode
396  * \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.
397  * \param argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
398  * \return pointer to last parameter or NULL when there is no any parameters.
399  */
400 char *cmd_parameter_last(int argc, char *argv[]);
401 
402 /** find command parameter by key and return value (next parameter) in int64.
403  * e.g. cmd: "mycmd mykey myvalue"
404  * \code
405  uint32_t i;
406  cmd_parameter_timestamp( argc, argv, "mykey", &i );
407  * \endcode
408  *
409  * Supports following formats:
410  * number -> direct conversion
411  * 11:22:33:44:55:66:77:88 -> converts to number
412  * seconds,tics -> converts thread type timestamp to int64
413  *
414  * \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.
415  * \param argv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
416  * \param key parameter key to be find
417  * \param value parameter value to be fetch, if key not found value are untouched.
418  * \return true if parameter key and value found otherwise false
419  */
420 bool cmd_parameter_timestamp(int argc, char *argv[], const char *key, int64_t *value);
421 
422 #ifdef __cplusplus
423 }
424 #endif
425 #endif /*_CMDLINE_H_*/
cmd_parameter_float
bool cmd_parameter_float(int argc, char *argv[], const char *key, float *value)
find command parameter by key and return value (next parameter) in float.
cmd_history_size
uint8_t cmd_history_size(uint8_t max)
Configure command history size (default 32)
cmd_parameter_val
bool cmd_parameter_val(int argc, char *argv[], const char *key, char **value)
find command parameter by key and return value (next parameter).
cmd_mutex_lock
void cmd_mutex_lock(void)
Retrieve output mutex lock This can be used to retrieve the output mutex when multiple cmd_printf/cmd...
cmd_ready
void cmd_ready(int retcode)
Command ready function for special cases.
cmd_output
void cmd_output(void)
Refresh output.
cmd_init_screen
void cmd_init_screen(void)
Initialize screen.
info
The key size.
Definition: kvstore_global_api.h:38
cmd_ctrl_func
void cmd_ctrl_func(void(*sohf)(uint8_t c))
Configure function, which will be called when Ctrl+A is pressed.
cmd_alias_add
void cmd_alias_add(const char *alias, const char *value)
Add alias to interpreter.
cmd_parameter_last
char * cmd_parameter_last(int argc, char *argv[])
Get last command line parameter as string.
cmd_vprintf
void cmd_vprintf(const char *fmt, va_list ap)
command line print function This function should be used when user want to print something to the con...
cmd_add
void cmd_add(const char *name, cmd_run_cb *callback, const char *info, const char *man)
Add command to intepreter.
cmd_run_cb
int( cmd_run_cb)(int argc, char *argv[])
Callback called when your command is run.
Definition: ns_cmdline.h:231
cmd_ready_cb_f
void( cmd_ready_cb_f)(int)
typedef for ready cb function
Definition: ns_cmdline.h:102
cmd_parameter_index
int cmd_parameter_index(int argc, char *argv[], const char *key)
find command parameter index by key.
cmd_set_ready_cb
void cmd_set_ready_cb(cmd_ready_cb_f *cb)
Configure cb which will be called after commands are executed or cmd_ready is called.
cmd_print_t
void( cmd_print_t)(const char *, va_list)
typedef for print functions
Definition: ns_cmdline.h:82
mbed::callback
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
cmd_echo_state
bool cmd_echo_state(void)
Get echo state.
cmd_exe
void cmd_exe(char *str)
Command executer.
cmd_printf
void cmd_printf(const char *fmt,...)
command line print function This function should be used when user want to print something to the con...
cmd_mutex_unlock
void cmd_mutex_unlock(void)
Release output mutex lock This can be used to release the output mutex once it has been retrieved wit...
cmd_variable_add
void cmd_variable_add(char *variable, char *value)
Add Variable to interpreter.
cmd_echo_on
void cmd_echo_on(void)
Echo on.
cmd_parameter_timestamp
bool cmd_parameter_timestamp(int argc, char *argv[], const char *key, int64_t *value)
find command parameter by key and return value (next parameter) in int64.
cmd_next
void cmd_next(int retcode)
execute next command if any
cmd_char_input
void cmd_char_input(int16_t u_data)
Enter character to console.
default_cmd_response_out
void default_cmd_response_out(const char *fmt, va_list ap)
default cmd response function, use stdout
cmd_request_screen_size
void cmd_request_screen_size(void)
Request screen size from host Response are stored to variables: COLUMNS and LINES - as integer values...
cmd_reset
void cmd_reset(void)
Reset cmdline to default values detach external commands, delete all variables and aliases...
cmd_parameter_bool
bool cmd_parameter_bool(int argc, char *argv[], const char *key, bool *value)
find command parameter by key.
cmd_mutex_release_func
void cmd_mutex_release_func(void(*mutex_release_f)(void))
Configure mutex wait function By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.
cmd_delete
void cmd_delete(const char *name)
delete command from intepreter
cmd_out_func
void cmd_out_func(cmd_print_t *outf)
Reconfigure default cmdline out function (cmd_printf)
cmd_parameter_int
bool cmd_parameter_int(int argc, char *argv[], const char *key, int32_t *value)
find command parameter by key and return value (next parameter) in integer.
cmd_free
void cmd_free(void)
Free cmd class.
cmd_variable_add_int
void cmd_variable_add_int(char *variable, int value)
Add integer variable to interpreter.
cmd_init
void cmd_init(cmd_print_t *outf)
Initialize cmdline class.
cmd_mutex_wait_func
void cmd_mutex_wait_func(void(*mutex_wait_f)(void))
Configure mutex wait function By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.
cmd_echo_off
void cmd_echo_off(void)
Echo off.
cmd_has_option
bool cmd_has_option(int argc, char *argv[], const char *key)
check if command option is present.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.