3 * Copyright 2003, 2006 Develer S.r.l. (http://www.develer.com/)
8 * \author Bernardo Innocenti <bernie@develer.com>
9 * \author Stefano Fedrigo <aleph@develer.com>
10 * \author Giovanni Bajo <rasky@develer.com>
12 * \brief serial protocol parser and commands.
17 *#* Revision 1.3 2006/07/19 12:56:28 bernie
18 *#* Convert to new Doxygen style.
20 *#* Revision 1.2 2006/06/12 21:37:02 marco
21 *#* implemented some commands (ver and sleep)
23 *#* Revision 1.1 2006/06/01 12:27:39 marco
24 *#* Added utilities for protocols
33 /** Max number of arguments and results for each command */
34 #define PARSER_MAX_ARGS 8
37 * Error generated by the commands through the return code.
41 RC_ERROR = -1, ///< Reply with error.
42 RC_OK = 0, ///< No reply (ignore reply arguments).
43 RC_REPLY = 1, ///< Reply command arguments.
44 RC_SKIP = 2 ///< Skip following commands
47 /** union that contains parameters passed to and from commands */
48 typedef union { long l; const char *s; } parms;
49 /** pointer to commands */
50 typedef ResultCode (*CmdFuncPtr)(parms args_results[]);
53 * Define a command that can be tokenized by the parser.
55 * The format strings are sequences of characters, one for each
56 * parameter/result. Valid characters are:
58 * d - a long integer, in decimal format
59 * s - a var string (in RAM)
61 * \note To create and fill an instance for this function, it is strongly
62 * advised to use \c DECLARE_CMD_HUNK (cmd_hunk.h).
66 const char *name; ///< Name of command
67 const char *arg_fmt; ///< Format string for the input
68 const char *result_fmt; ///< Format string for the output
69 CmdFuncPtr func; ///< Pointer to the handler function
70 uint16_t flags; ///< Currently unused.
74 * Initialize the parser module
76 * \note This function must be called before any other function in this module
78 void parser_init(void);
82 * Register a new command into the parser
84 * \param cmd Command template describing the command
87 void parser_register_cmd(const struct CmdTemplate* cmd);
91 * Hook for readline to provide completion support for the commands
92 * registered in the parser.
94 * \note This is meant to be used with mware/readline.c. See the
95 * documentation there for a description of this hook.
97 const char* parser_rl_match(void* dummy, const char* word, int word_len);
101 * \brief Command input handler.
103 * Process the input, calling the requested command
104 * (if found) and calling printResult() to give out
105 * the result (on device specified with parameter fd).
107 * \param line Text line to be processed (ASCIIZ)
109 * \return true if everything is OK, false in case of errors
111 bool parser_process_line(const char* line);
115 * Execute a command with its arguments, and fetch its results.
117 * \param templ Template of the command to be executed
118 * \param args Arguments for the command, and will contain the results
120 * \return False if the command returned an error, true otherwise
122 INLINE bool parser_execute_cmd(const struct CmdTemplate* templ, parms args[PARSER_MAX_ARGS])
124 return (templ->func(args) == 0);
129 * Find the template for the command contained in the text line.
130 * The template can be used to tokenize the command and interpret
133 * This function can be used to find out which command is contained
134 * in a given text line without parsing all the parameters and
137 * \param line Text line to be processed (ASCIIZ)
139 * \return The command template associated with the command contained
140 * in the line, or NULL if the command is invalid.
142 const struct CmdTemplate* parser_get_cmd_template(const char* line);
146 * Extract the arguments for the command contained in the text line.
148 * \param line Text line to be processed (ASCIIZ)
149 * \param templ Command template for this line
150 * \param args Will contain the extracted parameters
152 * \return True if everything OK, false in case of parsing error.
154 bool parser_get_cmd_arguments(const char* line, const struct CmdTemplate* templ, parms args[PARSER_MAX_ARGS]);
158 * Extract the ID from the command text line.
160 * \param line Text line to be processed (ASCIIZ)
161 * \param ID Will contain the ID extracted.
163 * \return True if everything ok, false if there is no ID
166 bool parser_get_cmd_id(const char* line, unsigned long* ID);
169 #endif /* PARSER_H */