µ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);

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);

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, 

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); 

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"));
    }
}