Doxygen Page for CLI / V0-1-1 / TV / linux-gcc

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "CLI/CLI_msgs.h"
#include "CLI/CLI_pubdefs.h"
#include "CLI_tv.h"


Classes
struct	_TV
	A virtual television. More...
Defines
#define	TV_M_BRIGHT 0x01
#define	TV_M_CHANNEL 0x02
#define	TV_M_CONTRAST 0x04
#define	TV_M_VOLUME 0x08
Typedefs
typedef struct _TV	TV
	Typedef for struct _TV.
Functions
static unsigned int	TV_decrease (CLI_Control , void )
	Handle the verb decrease.
static unsigned int	TV_exit (CLI_Control , void )
	Handle the verb exit.
static unsigned int	TV_help (CLI_Control , void )
	Handle the verb help.
static unsigned int	TV_increase (CLI_Control , void )
	Handle the verb increase.
static unsigned int	TV_power (CLI_Control , void )
	Turn the TV on and off.
static unsigned int	TV_set (CLI_Control , void )
	Callback for the set command.
static unsigned int	TV_setBright (CLI_Control , void )
	Set the brightness.
static unsigned int	TV_setChannel (CLI_Control , void )
	Set the channel.
static unsigned int	TV_setContrast (CLI_Control , void )
	Set the contrast.
static unsigned int	TV_setVolume (CLI_Control , void )
	Set the volume/mute.
static unsigned int	TV_show (CLI_Control , void )
	Show current settings.
static CLI_Syntax *	TV_syntax ()
	Define the TV syntax.
static void	TV_printPower (int)
	Useful utility to print the power state.
static void	TV_printSetting (TV *, int)
	Useful utility to print control settings.
static unsigned int	TV_delta (CLI_Control , void , int)
	Utility to handle the "increase" and "decrease" commands.
int	main (int argc, char *argv[])
	Main routine.
Variables
static const char *	s_abit = "abit"
	The string "abit".
static const char *	s_bright = "brightness"
	The string "brightness".
static const char *	s_channel = "channel"
	The string "channel".
static const char *	s_contrast = "contrast"
	The string "contrast".
static const char *	s_decrease = "decrease"
	The string "decrease".
static const char *	s_delta = "delta"
	The string "delta".
static const char *	s_exit = "exit"
	The string "exit".
static const char *	s_help = "help"
	The string "help".
static const char *	s_increase = "increase"
	The string "increase".
static const char *	s_lots = "lots"
	The string "lots".
static const char *	s_mute = "mute"
	The string "mute".
static const char *	s_off = "off"
	The string "off".
static const char *	s_on = "on"
	The string "on".
static const char *	s_power = "power"
	The string "power".
static const char *	s_set = "set"
	The string "set".
static const char *	s_show = "show"
	The string "show".
static const char *	s_some = "some"
	The string "some".
static const char *	s_volume = "volume"
	The string "volume".
static const char *	d_0 = "$0"
	The string "$0".
static const char *	f_decrease = "TV_decrease"
	The function name "TV_decrease".
static const char *	f_exit = "TV_exit"
	The function name "TV_exit".
static const char *	f_help = "TV_help"
	The function name "TV_help".
static const char *	f_increase = "TV_increase"
	The function name "TV_increase".
static const char *	f_power = "TV_power"
	The function name "TV_power".
static const char *	f_set = "TV_set"
	The function name "TV_set".
static const char *	f_setBright = "TV_setBright"
	The function name "TV_setBright".
static const char *	f_setChannel = "TV_setChannel"
	The function name "TV_setChannel".
static const char *	f_setContrast = "TV_setContrast"
	The function name "TV_setContrast".
static const char *	f_setVolume = "TV_setVolume"
	The function name "TV_setVolume".
static const char *	f_show = "TV_show"
	The function name "TV_show".

Detailed Description

Function Documentation

int main	(	int	argc,
		char *	argv[]
	)

Main routine.

How to drive a TV set in forty-two easy lessons.

static unsigned int TV_decrease	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Handle the verb decrease.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

Handle the verb decrease. Because the verbs increase and decrease are so similar, use a utility routine (TV_delta) to do the real work.

static unsigned int TV_delta	(	CLI_Control *	ctl,
		void *	user,
		int	sign
	)			`[static]`

Utility to handle the "increase" and "decrease" commands.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter
	sign	Increase or decrease

Returns:: Status code

Utility routine for TV_increase and TV_decrease. Here are some examples of valid "increase" or "decrease" commands:

increase constrast
decrease volume --delta=alot

The following examples are invalid:

increase (no control specified)
decrease volume --delta (if specified, delta must take a value)

static unsigned int TV_exit	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Handle the verb exit.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

The easiest verb to handle ... just return the CLI "request exit" code (CLI_ENDOFCMD). Don't forget to turn the TV off! The command looks like:

exit

static unsigned int TV_help	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Handle the verb help.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

Print a help page. The command looks like:

help

static unsigned int TV_increase	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Handle the verb increase.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

Handle the verb increase. Because the verbs increase and decrease are so similar, use a utility routine (TV_delta) to do the real work.

static unsigned int TV_power	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Turn the TV on and off.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

This implements the power on/off control. The only allowed syntaxes are:

power on
power off

static void TV_printPower ( int toggle ) [static]

Useful utility to print the power state.

Parameters:

toggle

The power state to print

static void TV_printSetting	(	TV *	tv,
		int	mask
	)			`[static]`

Useful utility to print control settings.

Parameters:

	tv	TV structure
	mask	Mask of settings to print

static unsigned int TV_set	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Callback for the set command.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

This routine is a callback for the set command. The standard set command in TV requires a parameter and then does a branch syntax. That makes this a "never call" routine. It is possible however to define a command like set without the required parameter, in which case a bare set command would end up here.

static unsigned int TV_setBright	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Set the brightness.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

This implements the set brightness command. Brightness is a value between 0-10. Values outside that range will brought back in bounds. Valid commands might look like:

set brightness 3
set brightness 8

Invalid commands would look like:

set brightness (parameter missing)
set brightness six (parameter is not an integer)
set brightness 6 typo (too many parameters)

static unsigned int TV_setChannel	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Set the channel.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

This implements the set channel command. Channel is a value between 1-500. Values outside that range will brought back in bounds. Valid commands might look like:

set channel 3 (perhaps you want to use your DVD/VCR)
set channel 432

Invalid commands would look like:

set channel (parameter missing)
set channel PBS (parameter is not an integer)
set channel 6 typo (too many parameters)

static unsigned int TV_setContrast	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Set the contrast.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

This implements the set contrast command. Contrast is a value between 0-10. Values outside that range will brought back in bounds. Valid commands might look like:

set contrast 3
set contrast 8

Invalid commands would look like:

set contrast (parameter missing)
set contrast alot (parameter is not an integer)
set contrast 6 typo (too many parameters)

static unsigned int TV_setVolume	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Set the volume/mute.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

This implements the set volume command. Volume is a value between 0-10. Values outside that range will brought back in bounds. The set volume command is a little more complicated than e.g. set contrast because it also accepts a (negatable) qualifier to mute the sound. To allow for the fact that the muting qualifier may be the only thing present, the value parameter is not mandated by the syntax.

In fact this is a very bad way to implement the mute function. It would make far more sense to add a primary command verb "mute" which takes a single keyword parameter "on" or "off" (much like the power command). Alternatively it could be implemented as a toggle ... just a simple one word command "mute" which mutes the first time it's issued and unmutes the second time. The value of implementing a poor syntax is that it demonstrates two features:

How to set up a "novalue" and "negatable" qualifier
Not all syntaxes can be adequately defined with the tools provided by CLI. Sometimes, the user has to do further logic checks in the callback routine.

Valid commands might look like:

set volume 3
set volume --mute
set volume 8 --nomute

Invalid commands would look like:

set volume (nothing to do ... but this routine must catch that)
set volume mute (mute is a qualifier, not a parameter)
set volume 6 typo --mute (too many parameters)

static unsigned int TV_show	(	CLI_Control *	ctl,
		void *	user
	)			`[static]`

Show current settings.

Parameters:

	ctl	Anonymous control pointer
	user	User parameter

Returns:: Status code

This implements the show command. If the show command is entered without a parameter, then all controls are displayed. If a parameter is provided, just that control is displayed. If the parameter is a comma separated list of controls, then the requested controls are displayed. Valid commands might look like:

show (shows all controls)
show volume (shows just the volume control)
show volume,contrast,channel (shows volume, contrast and channel)

Invalid commands would look like:

show volume contrast (not a comma separated list)
show mute (mute is not a control)

static CLI_Syntax * TV_syntax ( ) [static]

Define the TV syntax.

Returns:: Primary syntax pointer

Define a syntax to control a TV set.

This is where all the real work of setting up the syntax is done. TV defines two syntaxes: a primary syntax (the verbs decrease, increase, exit, help, power, set and show) and a secondary syntax (to handle the variants of the set command ... set brightness, set channel, set contrast and set volume).

To look at "internals", uncomment the "CLI_dmpdefs.h" include at the top of the file CLI_tv.c and then call any of the dump routines:

void CLI_dumpSyntax( CLI_Syntax *sntx ) Dump a specific syntax

void CLI_dumpSyntaxList( void ) Dump all known syntaxes

void CLI_dumpKeyList( CLI_KeyList *keys ) Dump a specific keyword list

void CLI_dumpKeyListList( void ) Dump all known keyword lists

void CLI_dumpParse( CLI_Control *ctl ) Dump the results of a parse (use in a callback routine)

`void CLI_dumpSyntax( CLI_Syntax *sntx )`	Dump a specific syntax
`void CLI_dumpSyntaxList( void )`	Dump all known syntaxes
`void CLI_dumpKeyList( CLI_KeyList *keys )`	Dump a specific keyword list
`void CLI_dumpKeyListList( void )`	Dump all known keyword lists
`void CLI_dumpParse( CLI_Control *ctl )`	Dump the results of a parse (use in a callback routine)

CLI_tv.c File Reference

Classes

Defines

Typedefs

Functions

Variables

Detailed Description

Function Documentation