...
From the caller point of view, once the commands have been developed and the initialization performed, all that is needed to do is a call the main µC/Shell execution function:
This function parses the ‘ in ’ parameter, a NUL terminated string containing a complete command line (command name, followed by possible arguments being separated by spaces), just like this one:
App_Test –a –b –c readme.txt
Once parsed, that is once the command name and its arguments have been extracted, µC/Shell looks into its command tables for a command match (in this case App_Test is the name of the command), and invokes it.
...
µC/Shell commands (i.e., commands placed in a ‘command table’) all have this prototype:
CPU_INT16S My_Cmd (CPU_INT16U argc,
CPU_CHAR *argv[],
SHELL_OUT_FNCT out_fnct,
SHELL_CMD_PARAM *pcmd_param);
where ‘argc’ is a count of the arguments supplied and ‘argv’, an array of pointers to the strings which are those arguments. As for the return value, it is command specific, and will be used as the return value for the Shell_Exec() function. However, in case of an error, SHELL_EXEC_ERR should be returned.
Commands are also defined by the SHELL_CMD_FNCT data type:
typedef CPU_INT16S (*SHELL_CMD_FNCT)(CPU_INT16U ,
CPU_CHAR **,
SHELL_OUT_FNCT ,
SHELL_CMD_PARAM *);
As s mentioned in the preceding section, each command is responsible for responding to its requester, and this is done with the help of the last parameter: the pointer to the output function. This function has the following prototype:
CPU_INT16S My_Out_Fnct (CPU_CHAR *pbuf,
CPU_INT16U buf_len,
void *popt);
where ‘pbuf’ is a pointer to a response buffer having a length of ‘buf_len’. The third parameter, ‘popt’, is an optional argument used to provide implementation specific information (port number, UART identification, etc.). As for the return value, it is suggested to return the number of data octets transmitted, SHELL_OUT_RTN_CODE_CONN_CLOSED if the link has been closed, and SHELL_OUT_ERR for any other error.
The output function is also defined by a data type, SHELL_OUT_FNCT:typedef CPU_INT16S (*SHELL_OUT_FNCT)(CPU_CHAR *,
CPU_INT16U ,
void * );
Finally the ‘pcmd_param’ is used to pass additional information to the command. The current implementation has provision for the current working directory, as well as an option parameter used by the output function:
typedef struct shell_cmd_param {
void *pcur_working_dir;
void *pout_opt;
CPU_BOOLEAN *psession_active;
} SHELL_CMD_PARAM;
Note that future implementation could add members to this structure to support more parameters.
...
µC/Shell startup code
We provide you with an example (i.e the application code) use of µC/Shell which is found in app.c and it was written to provide a startup example on how to use the capabilities of the µC/Shell module. app.c simply initializes µC/OS?II, µC/TCP-IP and µC/Shell, and creates a few tasks and other kernel objects that will give the user information about the state of the system. Note that you DO NOT need an RTOS like µC/OS?II or a TCP/IP stack like µC/TCP-IP to use µC/Shell.
...
This section of the manual will give you some examples of the above steps. Note that some sections of the source code have been removed or modified to help focus on the µC/Shell module use.
Listing 3-1 - Output function
CPU_INT16S App_TestShellOut (CPU_CHAR *pbuf, (1)
CPU_INT16U buf_len,
void *popt)
{
APP_TRACE_DEBUG((pbuf)); (2)
APP_TRACE_DEBUG((" executed.\n\r"));
return (buf_len); (3)
}
L3-1(1) Function implementing the ‘output’ facility. This function MUST have the prototype specified in section 2.01.
L3-1(2) This implementation simply outputs ‘pbuf’, using the trace mechanism (typically the console output).
L3-1(3) Returns the number of positive data octets transmitted (no error).
Listing 3-2 - Command
CPU_INT16S App_TestCmd (CPU_INT16U argc, (1)
...