Shell service API

Detailed Description

The shell service provides application-specific command-line interface.
It runs on asigned serial stream, parses the input text, decodes the command name and arguments and calls back user-specified functions assigned to each command.

After the Shell service is initialized by calling the fnet_shell_init() function, the user application should call the main service polling function fnet_service_poll() periodically in background.

For example:

...
// ************************************************************************
// *     The table of the main shell commands.
// *************************************************************************
 static const fnet_shell_command_t fapp_cmd_tab [] =
 {
     { "?", 0, 0, fnet_shell_help_cmd,"Display this help message.", ""},
     { "set", 0, 2, fapp_set_cmd, "Set parameter.", "[<parameter> <value>]"},
     { "show", 0, 0, fapp_show, "Show parameters.", "" },
     { "info", 0, 0, fapp_netif_info_cmd, "Show interface info.", ""},
     { "dhcp", 0, 1, fapp_dhcp_cln_cmd, "Start DHCP client.", "[release|reboot]"},
     { "http", 0, 1, fapp_http_srv_cmd, "Start HTTP Server.", "[release]"},
     { 0, 0, 0, 0, 0, 0},
 };
// ************************************************************************
// *     The main shell control data structure.
// *************************************************************************
fnet_shell_t fapp_shell =
{
  fapp_cmd_tab,
  "PROMT> ",
  fapp_shell_on_init,
};
fnet_shell_desc_t fapp_shell_desc = 0; // Shell descriptor.
...
...
main()
{
  fnet_shell_params_t shell_params;
  ...
  shell_params.shell = &fapp_shell;
  shell_params.cmd_line_buffer = fapp_cmd_line_buffer;
  shell_params.cmd_line_buffer_size = sizeof(fapp_cmd_line_buffer);
  shell_params.stream = FNET_SERIAL_STREAM_DEFAULT; // Use default stream.
  shell_params.echo = FNET_TRUE; // Enable echo.
  ...
  if((fapp_shell_desc = fnet_shell_init(&shell_params)) != 0)
  {
      fnet_printf("\n Shell started.\n");
      while(1)
      {
          // Do something.
          ...
          fnet_service_poll();
      }
   }
   else
   {
       fnet_printf("\n Shell initialization is failed.\n");
   }
  ...
}

For Shell service usage example, refer to FNET demo application source code.

Configuration parameters:

• FNET_CFG_SHELL_MAX
• FNET_CFG_SHELL_ARGS_MAX
• FNET_CFG_SHELL_HELP_FORMAT

Data Structures
struct	fnet_shell_command_t
	Shell command control structure. More...
struct	fnet_shell_t
	Shell main control structure. More...
struct	fnet_shell_params_t
	Input parameters for fnet_shell_init(). More...

Macros
#define	FNET_SHELL_QUOTE_SYMBOL   '\''
	The quote (') symbol is used to combine multiple words to one argument. . More...
#define	FNET_SHELL_ESCAPE_SYMBOL   '\\'
	The escape symbol (). More...
#define	FNET_SHELL_COMMAND_SPLITTER   ';'
	Split symbol used to split shell commands. User may enter several commands in one command line, but they must be split by this symbol. . More...

Typedefs
typedef void *	fnet_shell_desc_t
	Shell service descriptor. More...
typedef void(*	fnet_shell_cmd_function_t) (fnet_shell_desc_t desc, fnet_index_t argc, fnet_char_t **argv)
	Command callback function prototype. More...

Enumerations
enum	fnet_shell_state_t {   FNET_SHELL_STATE_DISABLED,   FNET_SHELL_STATE_INIT,   FNET_SHELL_STATE_GET_USER_INPUT,   FNET_SHELL_STATE_EXEC_CMD,   FNET_SHELL_STATE_BLOCKED,   FNET_SHELL_STATE_END_CMD }
	Shell states. Used mainly for debugging purposes. More...

Functions
fnet_shell_desc_t	fnet_shell_init (fnet_shell_params_t *params)
	Initializes the Shell service. More...
void	fnet_shell_release (fnet_shell_desc_t desc)
	Releases the Shell service. More...
void	fnet_shell_help (fnet_shell_desc_t desc)
	Prints the command-shell help message. More...
fnet_return_t	fnet_shell_script (fnet_shell_desc_t desc, fnet_char_t *script)
	Executes the command line script. More...
void	fnet_shell_script_stop (fnet_shell_desc_t desc)
	Stops execution of the shell command line. More...
fnet_return_t	fnet_shell_block (fnet_shell_desc_t desc, void(*on_ctrlc)(fnet_shell_desc_t shl_desc, void *cookie), void *cookie)
	Blocks the shell to ignore user commands. More...
void	fnet_shell_unblock (fnet_shell_desc_t desc)
	Unblocks the shell to accept user commands. More...
fnet_size_t	fnet_shell_printf (fnet_shell_desc_t desc, const fnet_char_t *format,...)
	Prints formatted text to the shell stream. More...
fnet_size_t	fnet_shell_println (fnet_shell_desc_t desc, const fnet_char_t *format,...)
	Prints formatted text to the shell stream and terminates the printed text by the line separator string. More...
void	fnet_shell_putchar (fnet_shell_desc_t desc, fnet_char_t character)
	Writes character to the shell stream. More...
fnet_int32_t	fnet_shell_getchar (fnet_shell_desc_t desc)
	Reads character from the shell stream. More...
fnet_return_t	fnet_shell_switch (fnet_shell_desc_t desc, const fnet_shell_t *switch_shell)
	Switch to other command line set. More...
fnet_bool_t	fnet_shell_is_ctrlc (fnet_shell_desc_t desc)
	Detects if the [Ctrl]+[c] is received. More...
const fnet_shell_command_t *	fnet_shell_get_command_by_name (fnet_shell_desc_t desc, const fnet_char_t *name)
	Looks for a shell command by its name. More...