mirror of
https://github.com/NevermindZZT/letter-shell.git
synced 2025-01-21 10:02:54 +08:00
171 lines
6.0 KiB
Markdown
171 lines
6.0 KiB
Markdown
# shell_enhance
|
||
|
||
|
||
|
||
|
||
|
||
|
||
- [shell_enhance](#shell_enhance)
|
||
- [简介](#简介)
|
||
- [组件](#组件)
|
||
- [shell_cmd_group](#shell_cmd_group)
|
||
- [shell_passthrough](#shell_passthrough)
|
||
- [shell_secure_user](#shell_secure_user)
|
||
|
||
## 简介
|
||
|
||
`shell_enhance`是`letter shell 3.0`上用于增强shell功能的组件，`shell_enhance`分离了一些不常用的shell功能，对于需要这些功能的用户，只需要将对应的文件加入到编译系统中即可
|
||
|
||
## 组件
|
||
|
||
`shell_enhance`目前包含的组件如下：
|
||
|
||
| 组件 | 描述 | 依赖文件 |
|
||
| ----------------- | -------------- | --------------------------------------- |
|
||
| shell_cmd_group | 提供命令组功能 | shell_cmd_group.c shell_cmd_group.h |
|
||
| shell_passthrough | 提供透传功能 | shell_passthrough.c shell_passthrough.h |
|
||
| shell_secure_user | 安全用户功能 | shell_secure_user.c shell_secure_user.h |
|
||
|
||
### shell_cmd_group
|
||
|
||
`shell_cmd_group`提供了一个命令组的功能，用户可以将多个相关的命令打包成一个命令组，然后通过形如`cmdgroup subcmd [param]`的方式进行命令调用
|
||
|
||
- 定义命令数组
|
||
|
||
命令数组用于将多个命令关联到一个数组，这个数组就是定义命令组需要的，你需要想正常命令一样，为每个子命令对应定义一个函数，然后将他们添加到一个数组中，可以使用宏`SHELL_CMD_GROUP_ITEM`进行定义
|
||
|
||
```c
|
||
int test(int a, char *b)
|
||
{
|
||
printf("hello world, %d, %s\r\n", a, b);
|
||
return 0;
|
||
}
|
||
|
||
int test2(int argc, char *argv[])
|
||
{
|
||
printf("%d parameters\r\n", argc);
|
||
for (short i = 0; i < argc; i++)
|
||
{
|
||
printf("%s\t", argv[i]);
|
||
}
|
||
printf("\r\n");
|
||
}
|
||
|
||
ShellCommand testGroup[] =
|
||
{
|
||
SHELL_CMD_GROUP_ITEM(SHELL_TYPE_CMD_FUNC, test, test, command group test1),
|
||
SHELL_CMD_GROUP_ITEM(SHELL_TYPE_CMD_MAIN, test2, test2, command group test2),
|
||
SHELL_CMD_GROUP_END()
|
||
};
|
||
```
|
||
|
||
其中`SHELL_CMD_GROUP_END()`需要写在每个命令数组的最后
|
||
|
||
- 定义命令组
|
||
|
||
使用宏`SHELL_EXPORT_CMD_GROUP`定义命令组
|
||
|
||
```c
|
||
SHELL_EXPORT_CMD_GROUP(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_MAIN), gt, testGroup, command group test);
|
||
```
|
||
|
||
- 调用
|
||
|
||
在命令行，使用`cmdgroup subcmd [param]`的形式调用命令
|
||
|
||
```sh
|
||
letter:/$ gt test 666 Letter
|
||
hello world, 666, Letter
|
||
Return: 0, 0x00000000
|
||
|
||
letter:/$ gt test2 hello world
|
||
3 parameters
|
||
test2 hello world
|
||
Return: 0, 0x00000000
|
||
```
|
||
|
||
- 命令帮助
|
||
|
||
通过使用`cmdgroup -h`的方式查看完整的命令帮助信息
|
||
|
||
```sh
|
||
letter:/$ gt -h
|
||
command group help of gt
|
||
test: command group test1
|
||
test2: command group test2
|
||
Return: 0, 0x00000000
|
||
```
|
||
|
||
### shell_passthrough
|
||
|
||
`shell_passthrough`提供了一个透传模式的功能，用户可以定义一个透传命令，执行透传命令后进入对应的透传模式，此后，命令行接收到的数据将以行为单位透传到定义的`handler`中，此扩展适用于一些需要进行终端数据转发的场景，常见的场景比如说通过命令行发送AT指令
|
||
|
||
- 定义hanadler
|
||
|
||
passthrough模式需要定义一个函数，用于处理命令行传过来的数据，函数原型为`typedef int (*ShellPassthrough)(char *data, unsigned short len)`
|
||
|
||
```C
|
||
void shellPassthroughTest(char *data, unsigned short len)
|
||
{
|
||
printf("passthrough mode test, data: %s, len: %d\r\n", data, len);
|
||
}
|
||
```
|
||
|
||
- 定义passthrough
|
||
|
||
使用宏`SHELL_EXPORT_PASSTROUGH`定义`passthrough`
|
||
|
||
```C
|
||
SHELL_EXPORT_PASSTROUGH(SHELL_CMD_PERMISSION(0), passTest, passthrough>>, shellPassthroughTest, passthrough mode test);
|
||
```
|
||
|
||
- 调用
|
||
|
||
直接在命令行输入定义的`passthrough`名字可进入对应的透传模式，之后在输入的数据会按照行为单位通过`handler`调用
|
||
|
||
```sh
|
||
letter:/mnt/f/Github/letter shell/demo/x86-gcc$ passTest
|
||
passthrough>>hello
|
||
passthrough mode test, data: hello, len: 5
|
||
```
|
||
|
||
- 退出
|
||
|
||
使用组合键`Ctrl + D`退出`passthrough`，键值可以在`shell_passthrough.h`文件中的`SHELL_PASSTHROUGH_EXIT_KEY`宏修改
|
||
|
||
- 单次调用
|
||
|
||
某些情况下，使用`passthrough`模式时，我们可能只需要单次数据的透传，此时可以不进入`passthrough`命令行，直接调用命令带上透传的数据即可
|
||
|
||
```sh
|
||
letter:/mnt/f/Github/letter shell/demo/x86-gcc$ passTest "hello world"
|
||
passthrough mode test, data: hello world, len: 11
|
||
```
|
||
|
||
### shell_secure_user
|
||
|
||
`shell_secure_user`组件是对shell用户的一个补充，在`letter shell`中，我们可以通过定义不同的用户和分配命令权限，约束使用者可以执行的命令，可以将高权限的用户定义密码，但是，shell用户的默认实现只支持固定的密码，在编译时就已经确定，安全性不高
|
||
|
||
使用`shell_secure_user`组件，我们可以定义一个函数，使用这个函数得到用户的密码，一般的，我们可以根据芯片的ID，mac地址，甚至可以向服务器做请求以获取密码，提高安全性
|
||
|
||
- 定义获取用户密码函数(handler)
|
||
|
||
示例函数直接返回用户名作为密码，实际使用时可以通过任何方式计算或者获取密码，注意，此处返回的密码字符串，请自行分配内存保存
|
||
|
||
```c
|
||
char *shellSecureUserHandlerTest(const char *name)
|
||
{
|
||
return (char *)name;
|
||
}
|
||
```
|
||
|
||
- 定义用户
|
||
|
||
```c
|
||
SHELL_EXPORT_SECURE_USER(SHELL_CMD_PERMISSION(0xFF), secure, shellSecureUserHandlerTest, secure user test);
|
||
```
|
||
|
||
- 调用
|
||
|
||
使用`shell_secure_user`定义的用户和shell默认用户调用方法完全一致，只需要在shell命令行输入用户名和密码即可
|