mware/parser.h

   1 /**
   2  * \file
   3  * Copyright 2003, 2006 Develer S.r.l. (http://www.develer.com/)
   4  * All Rights Reserved.
   5  *
   6  * \version $Id$
   7  *
   8  * \author Bernardo Innocenti <bernie@develer.com>
   9  * \author Stefano Fedrigo <aleph@develer.com>
  10  * \author Giovanni Bajo <rasky@develer.com>
  11  *
  12  * \brief serial protocol parser and commands.
  13  */
  14
  15 /*#*
  16  *#* $Log$
  17  *#* Revision 1.3  2006/07/19 12:56:28  bernie
  18  *#* Convert to new Doxygen style.
  19  *#*
  20  *#* Revision 1.2  2006/06/12 21:37:02  marco
  21  *#* implemented some commands (ver and sleep)
  22  *#*
  23  *#* Revision 1.1  2006/06/01 12:27:39  marco
  24  *#* Added utilities for protocols
  25  *#*
  26  *#*/
  27
  28 #ifndef PARSER_H
  29 #define PARSER_H
  30
  31 #include <drv/ser.h>
  32
  33 /** Max number of arguments and results for each command */
  34 #define PARSER_MAX_ARGS       8
  35
  36 /**
  37  * Error generated by the commands through the return code.
  38  */
  39 typedef enum
  40 {
  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
  45 } ResultCode;
  46
  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[]);
  51
  52 /**
  53  * Define a command that can be tokenized by the parser.
  54  *
  55  * The format strings are sequences of characters, one for each
  56  * parameter/result. Valid characters are:
  57  *
  58  *  d - a long integer, in decimal format
  59  *  s - a var string (in RAM)
  60  *
  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).
  63  */
  64 struct CmdTemplate
  65 {
  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.
  71 };
  72
  73 /**
  74  * Initialize the parser module
  75  *
  76  * \note This function must be called before any other function in this module
  77  */
  78 void parser_init(void);
  79
  80
  81 /**
  82  * Register a new command into the parser
  83  *
  84  * \param cmd Command template describing the command
  85  *
  86  */
  87 void parser_register_cmd(const struct CmdTemplate* cmd);
  88
  89
  90 /**
  91  * Hook for readline to provide completion support for the commands
  92  * registered in the parser.
  93  *
  94  * \note This is meant to be used with mware/readline.c. See the
  95  * documentation there for a description of this hook.
  96  */
  97 const char* parser_rl_match(void* dummy, const char* word, int word_len);
  98
  99
 100 /**
 101  * \brief Command input handler.
 102  *
 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).
 106  *
 107  * \param line Text line to be processed (ASCIIZ)
 108  *
 109  * \return true if everything is OK, false in case of errors
 110  */
 111 bool parser_process_line(const char* line);
 112
 113
 114 /**
 115  * Execute a command with its arguments, and fetch its results.
 116  *
 117  * \param templ Template of the command to be executed
 118  * \param args Arguments for the command, and will contain the results
 119  *
 120  * \return False if the command returned an error, true otherwise
 121  */
 122 INLINE bool parser_execute_cmd(const struct CmdTemplate* templ, parms args[PARSER_MAX_ARGS])
 123 {
 124         return (templ->func(args) == 0);
 125 }
 126
 127
 128 /**
 129  * Find the template for the command contained in the text line.
 130  * The template can be used to tokenize the command and interpret
 131  * it.
 132  *
 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
 135  * executing it.
 136  *
 137  * \param line Text line to be processed (ASCIIZ)
 138  *
 139  * \return The command template associated with the command contained
 140  * in the line, or NULL if the command is invalid.
 141  */
 142 const struct CmdTemplate* parser_get_cmd_template(const char* line);
 143
 144
 145 /**
 146  * Extract the arguments for the command contained in the text line.
 147  *
 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
 151  *
 152  * \return True if everything OK, false in case of parsing error.
 153  */
 154 bool parser_get_cmd_arguments(const char* line, const struct CmdTemplate* templ, parms args[PARSER_MAX_ARGS]);
 155
 156
 157 /**
 158  * Extract the ID from the command text line.
 159  *
 160  * \param line Text line to be processed (ASCIIZ)
 161  * \param ID Will contain the ID extracted.
 162  *
 163  * \return True if everything ok, false if there is no ID
 164  *
 165  */
 166 bool parser_get_cmd_id(const char* line, unsigned long* ID);
 167
 168
 169 #endif /* PARSER_H */
 170