BeRTOS
|
Channel protocol parser and commands. More...
Data Structures | |
union | parms |
union that contains parameters passed to and from commands More... | |
struct | CmdTemplate |
Define a command that can be tokenized by the parser. More... | |
Defines | |
#define | REGISTER_CMD(NAME) REGISTER_FUNCTION(&cmd_ ## NAME ## _template) |
Utility function to register a command. | |
#define | MAKE_TEMPLATE(NAME, ARGS, RES, FLAGS) |
Utility macro to create a command template. | |
#define | MAKE_CMD(NAME, ARGS, RES, BODY, FLAGS) |
Utility macro to create command templates and callback functions. | |
Typedefs | |
typedef ResultCode(* | CmdFuncPtr )(parms args_results[]) |
pointer to commands | |
Enumerations | |
enum | ResultCode { RC_ERROR = -1, RC_OK = 0, RC_REPLY = 1, RC_SKIP = 2 } |
Error generated by the commands through the return code. More... | |
Functions | |
void | parser_init (void) |
Initialize the parser module. | |
void | parser_register_cmd (const struct CmdTemplate *cmd) |
Register a new command into the parser. | |
const char * | parser_rl_match (void *dummy, const char *word, int word_len) |
Hook for readline to provide completion support for the commands registered in the parser. | |
bool | parser_process_line (const char *line) |
Command input handler. | |
bool | parser_execute_cmd (const struct CmdTemplate *templ, parms args[CONFIG_PARSER_MAX_ARGS]) |
Execute a command with its arguments, and fetch its results. | |
struct CmdTemplate * | parser_get_cmd_template (const char *line) |
Find the template for the command contained in the text line. | |
bool | parser_get_cmd_arguments (const char *line, const struct CmdTemplate *templ, parms args[CONFIG_PARSER_MAX_ARGS]) |
Extract the arguments for the command contained in the text line. |
Channel protocol parser and commands.
This module provides a simple text based RPC implementation. Often there is the need to give a command to the device and receive results back. Each command may have a variable number of input and output parameters, with variable type, and a return code which indicates if the command was successfully executed or not; this module provides the machinery to facilitate the above RPC scenario. You will need to write the RPC input and reply code as well as the definition of the commands.
Commands are defined using a CmdTemplate struct containing:
Once you have declared the commands, you need to register them in the parser with the function parser_register_cmd(). You are strongly encouraged to use MAKE_CMD() (or alternatively MAKE_TEMPLATE()) and REGISTER_CMD() to declare and register commands.
A command line can be parsed with the following steps:
You can also provide interactive command line completion using parser_rl_match().
Example:
// Declare a buzzer command MAKE_CMD(beep, "d", "", ({ buz_beep(args[1].l); RC_OK; }), 0) // initialize the parser parser_init(); REGISTER_CMD(beep); // parse an input line char buf[80]; // read line from somewhere rpc_get(buf); // now parse the line const struct CmdTemplate *templ; templ = parser_get_cmd_template(buf); // Take arguments (optionally check errors) parms args[PARSER_MAX_ARGS]; parser_get_cmd_arguments(buf, templ, args); //Execute command if(!parser_execute_cmd(templ, args)) { // error } // Now args contain the outputs of the function, you can send it // back to the caller rpc_reply(args)
Configuration file: cfg_parser.h
#define MAKE_CMD | ( | NAME, | |
ARGS, | |||
RES, | |||
BODY, | |||
FLAGS | |||
) |
static ResultCode cmd_ ## NAME (parms *args) \ { \ return (ResultCode)BODY; \ } \ MAKE_TEMPLATE(NAME, ARGS, RES, FLAGS)
Utility macro to create command templates and callback functions.
Example for a version command:
MAKE_CMD(ver, "", "ddd", ({ args[1].l = VERS_MAJOR; args[2].l = VERS_MINOR; args[3].l = VERS_REV; RC_OK; }), 0);
Remember that input and output parameters start from index 1, since args[0] is the command itself. The last line is the return value of the function.
NAME | Command name matched by the parser |
ARGS | Input arguments to the command |
RES | Output arguments of the command |
BODY | Command body, expressed with C 'statement expression' |
FLAGS | Command flags |
#define MAKE_TEMPLATE | ( | NAME, | |
ARGS, | |||
RES, | |||
FLAGS | |||
) |
const struct CmdTemplate cmd_ ## NAME ## _template = \ { \ #NAME, ARGS, RES, cmd_ ## NAME, FLAGS \ };
Utility macro to create a command template.
It requires that a callback function with name cmd_NAME is already defined.
NAME | Command name |
ARGS | Input arguments |
RES | Output arguments |
FLAGS | Command flags |
#define REGISTER_CMD | ( | NAME | ) | REGISTER_FUNCTION(&cmd_ ## NAME ## _template) |
enum ResultCode |
bool parser_execute_cmd | ( | const struct CmdTemplate * | templ, |
parms | args[CONFIG_PARSER_MAX_ARGS] | ||
) | [inline] |
Execute a command with its arguments, and fetch its results.
The args paramenter is value-result: it provides input arguments to the callback function and it stores output values on return.
templ | Template of the command to be executed |
args | Arguments for the command, and will contain the results |
bool parser_get_cmd_arguments | ( | const char * | input, |
const struct CmdTemplate * | cmdp, | ||
parms | args[CONFIG_PARSER_MAX_ARGS] | ||
) |
Extract the arguments for the command contained in the text line.
The first argument will always be the command name, so the actual arguments will start at index 1.
input | Text line to be processed (ASCIIZ) |
cmdp | Command template for this line |
args | Will contain the extracted parameters |
struct CmdTemplate* parser_get_cmd_template | ( | const char * | input | ) | [read] |
Find the template for the command contained in the text line.
The template can be used to tokenize the command and interpret it.
This function can be used to find out which command is contained in a given text line without parsing all the parameters and executing it.
input | Text line to be processed (ASCIIZ) |
void parser_init | ( | void | ) |
bool parser_process_line | ( | const char * | input | ) |
void parser_register_cmd | ( | const struct CmdTemplate * | cmd | ) |
const char* parser_rl_match | ( | void * | dummy, |
const char * | word, | ||
int | word_len | ||
) |
Hook for readline to provide completion support for the commands registered in the parser.