Simple RPC machinery
[Middleware facilities]

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)
	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.
bool	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.
bool	parser_get_cmd_id (const char *line, unsigned long *ID)
	Extract the ID from the command text line.

---

Detailed Description

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:

• command name: the string that will be matched by the parser;
• command arguments: a string representing type and number of input arguments;
• command output: a string representing type and number of output arguments;
• function callback: function implementing the command.

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:

• find the corresponding command template with parser_get_cmd_template()
• extract command arguments with parser_get_cmd_arguments()
• execute the command with parser_execute_cmd()

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

Author:

Bernie Innocenti <bernie@codewiz.org>

Stefano Fedrigo <aleph@develer.com>

Giovanni Bajo <rasky@develer.com>

---

Define Documentation

#define MAKE_CMD	(	NAME,
		ARGS,
		RES,
		BODY,
		FLAGS		)

Value:

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.

Parameters:

	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

Definition at line 213 of file parser.h.

#define MAKE_TEMPLATE	(	NAME,
		ARGS,
		RES,
		FLAGS		)

Value:

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.

Parameters:

	NAME	Command name
	ARGS	Input arguments
	RES	Output arguments
	FLAGS	Command flags

Definition at line 183 of file parser.h.

#define REGISTER_CMD

(

NAME

)

Value:

do { \
        if (!REGISTER_FUNCTION(&cmd_ ## NAME ## _template)) \
            ASSERT2(0, "Error in registering command, no space left"); \
    } while (0)

Utility function to register a command.

Parameters:

NAME

Command name to register

Definition at line 167 of file parser.h.

---

Enumeration Type Documentation

enum ResultCode

Error generated by the commands through the return code.

Enumerator:

RC_ERROR	Reply with error.
RC_OK	No reply (ignore reply arguments).
RC_REPLY	Reply command arguments.
RC_SKIP	Skip following commands.

Definition at line 126 of file parser.h.

---

Function Documentation

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.

Parameters:

	templ	Template of the command to be executed
	args	Arguments for the command, and will contain the results

Returns:

False if the command returned an error, true otherwise

Definition at line 252 of file parser.h.

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.

Parameters:

	input	Text line to be processed (ASCIIZ)
	cmdp	Command template for this line
	args	Will contain the extracted parameters

Returns:

True if everything OK, false in case of parsing error.

Definition at line 261 of file parser.c.

bool parser_get_cmd_id	(	const char *	line,
		unsigned long *	ID
	)

Extract the ID from the command text line.

Parameters:

	line	Text line to be processed (ASCIIZ)
	ID	Will contain the ID extracted.

Returns:

True if everything ok, false if there is no ID

Definition at line 185 of file parser.c.

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.

Parameters:

input

Text line to be processed (ASCIIZ)

Returns:

The command template associated with the command contained in the line, or NULL if the command is invalid.

Definition at line 216 of file parser.c.

void parser_init

(

void

)

Initialize the parser module.

Note:

This function must be called before any other function in this module

Definition at line 319 of file parser.c.

bool parser_process_line

(

const char *

input

)

Command input handler.

Process the input, calling the requested command (if found).

Parameters:

input

Text line to be processed (ASCIIZ)

Returns:

true if everything is OK, false in case of errors

Definition at line 290 of file parser.c.

bool parser_register_cmd

(

const struct CmdTemplate *

cmd

)

Register a new command into the parser.

Parameters:

cmd

Command template describing the command

Returns:

true if registration was successful, false otherwise

Definition at line 314 of file parser.c.

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.

Note:

This is meant to be used with mware/readline.c. See the documentation there for a description of this hook.