µC/Shell API Reference
This section provides a reference to the µC/Shell API. Each of the user-accessible services is presented in alphabetical order. The following information is provided for each of those services:
A brief description
The function prototype
The filename of the source code
A description of the arguments passed to the function
A description of the returned value(s)
Specific notes and warnings on using the service
A usage example
Shell_CmdTblAdd()
void Shell_CmdTblAdd (CPU_CHAR *cmd_tbl_name,
SHELL_CMD cmd_tbl[],
SHELL_ERR *perr);
File | Called from |
| Application |
Allocates and initializes a module command, and inserts a command table into it.
Arguments
cmd_tbl_name
Pointer to character string representing the name of the command table.
cmd_tbl
Command table to add.
perr
Pointer to variable that will receive the return error code from this function :
SHELL_ERR_NONE
No error.
SHELL_ERR_NULL_PTR
Argument 'cmd_tbl' passed a NULL pointer.
SHELL_ERR_MODULE_CMD_EMPTY
Command table empty.
SHELL_ERR_MODULE_CMD_ALREADY_IN
Command table already added, or command table name already used.
SHELL_ERR_MODULE_CMD_NONE_AVAIL
NO available module command to allocate.
SHELL_ERR_MODULE_CMD_NAME_NONE
No module command name found.
SHELL_ERR_MODULE_CMD_NAME_TOO_LONG
Module command name too long.
SHELL_ERR_MODULE_CMD_NAME_COPY
Copy error.
Returned Values
None.
Notes/Warnings
The 'cmd_tbl_ame' argument is the prefix of the commands in 'cmd_tbl'. In order to speed up the command search, the shell first locate the appropriate table based on the prefix of the command. Hence, it is recommended that all commands in a table be named with the same prefix. For instance, µC/TCP-IP related command displaying statistics could look like :
Net_stats
while a file system command listing the current directory would be :
FS_ls
The names of those module commands are respectively 'Net' and 'FS'.
Example
static SHELL_CMD App_ShellAppCmdTbl[] = {
{"App_test", App_TestShellCmd},
{0, 0}
};
void App_CmdTblAdd (void)
{
SHELL_ERR err;
APP_TRACE_DEBUG(("Adding Shell command table ... "));
Shell_CmdTblAdd("App", App_ShellAppCmdTbl, &err);
if (err == SHELL_ERR_NONE) {
APP_TRACE_DEBUG(("done.\n\r"));
} else {
APP_TRACE_DEBUG(("failed.\n\r"));
}
}
Shell_CmdTblRem ()
void Shell_CmdTblRem (CPU_CHAR *cmd_tbl_name,
SHELL_ERR *perr);
File | Called from |
| Application |
Removes a command table from the shell.
Arguments
cmd_tbl_name
Pointer to character string representing the name of the command table.
perr
Pointer to variable that will receive the return error code from this function:
SHELL_ERR_NONE
No error.
SHELL_ERR_NULL_PTR
Argument 'cmd_tbl_name' passed a NULL pointer.
SHELL_ERR_MODULE_CMD_NOT_FOUND
Module command NOT found.
Returned Values
None.
Notes/Warnings
None.
Example
void App_CmdTblRem (void)
{
SHELL_ERR err;
APP_TRACE_DEBUG(("Removing Shell command table ... "));
Shell_CmdTblRem("App", &err);
if (err == SHELL_ERR_NONE) {
APP_TRACE_DEBUG(("done.\n\r"));
} else {
APP_TRACE_DEBUG(("failed.\n\r"));
}
}
Shell_Exec ()
CPU_INT16S Shell_Exec (CPU_CHAR *in,
SHELL_OUT_FNCT out_fnct,
File | Called from |
| Application |
Parses and executes the command passed in parameter.
Arguments
in
Pointer to a CPU_CHAR string holding a complete command and its argument(s).
out_fnct
Pointer to 'output' function used by command.
perr
Pointer to variable that will receive the return error code from this function:
SHELL_ERR_NONE
No error.
SHELL_ERR_NULL_PTR
Argument 'in' passed a NULL pointer.
SHELL_ERR_CMD_NOT_FOUND
Command NOT found.
SHELL_ERR_CMD_SEARCH
Error searching for command.
SHELL_ERR_CMD_EXEC
Error executing command.
SHELL_ERR_ARG_TBL_FULL
Argument table full and token still to be parsed.
Returned Values
SHELL_EXEC_ERR
If command executing error.
Command specific return value
Otherwise.
Notes/Warnings
The command may generate some output that should be transmitted to some device (socket, RS-232 link, ...). The caller of this function is hence responsible for the implementation of such function, if output is desired.
Example
void App_Exec (void)
{
SHELL_ERR err;
APP_TRACE_DEBUG(("Testing Shell, executing command ...\n\r"));
Shell_Exec("App_test -a -b -c", &App_TestShellOut, &err);
switch (err) {
case SHELL_ERR_NONE:
APP_TRACE_DEBUG(("Command executed, no error.\n\r"));
break;
case SHELL_ERR_NULL_PTR:
APP_TRACE_DEBUG(("Error, NULL pointer passed.\n\r"));
break;
case SHELL_ERR_CMD_NOT_FOUND:
APP_TRACE_DEBUG(("Error, command NOT found.\n\r"));
break;
case SHELL_ERR_CMD_SEARCH:
APP_TRACE_DEBUG(("Error, searching command.\n\r"));
break;
case SHELL_ERR_ARG_TBL_FULL:
APP_TRACE_DEBUG(("Error, too many arguments\n\r"));
break;
case SHELL_ERR_CMD_EXEC:
APP_TRACE_DEBUG (("Error, executing command.\n\r"));
break;
default:
break;
}
}
Shell_Init()
CPU_BOOLEAN Shell_Init (void);
File | Called from |
| Application |
Initializes the shell.
Arguments
None
Returned Values
DEF_OK
Shell initialization successful.
DEF_FAIL
Otherwise.
Notes/Warnings
The Shell_Init() function must be called before the other Shell function are invoked. Shell_Init() must also only be called once from product's application.
Example
void App_Init (void)
{
CPU_BOOLEAN success;
SHELL_ERR err;
APP_TRACE_DEBUG(("Initialize shell ... "));
Success = Shell_Init();
if (success == DEF_OK) {
APP_TRACE_DEBUG(("done.\n\r"));
} else {
APP_TRACE_DEBUG(("failed.\n\r"));
}
}