物联网操作系统HelloX应用编程指南
HelloX操作系统应用编程指南
HelloX应用开发概述
可以通过三种方式，在HelloX操作系统基础上开发应用:
1． 以内部命令方式实现应用，直接编译链接到HelloX的内核shell中。这时候应用代码的执行上下文，是shell线程的上下文。应用程序代码不会单独成为一个独立的线程；
2． 以外部命令方式实现应用。直接编译链接到HelloX的内核中，通过shell来启动应用。这时候的应用，内核会创建一个独立的线程来承载；
3． 以外部应用方式实现应用。应用代码单独编译链接，完成后存放在安装了HelloX操作系统的计算机存储设备中。在shell下，使用loadapp命令，加载可执行的应用模块。这种方式下，应用代码也是在一个独立的线程中执行的。需要注意的是，在这种方式下，应用代码只能调用HelloX SDK提供的API接口函数和C库函数。
本文主要对第一种和第二种实现方式进行说明。
以内部命令方式实现应用
内部命令采用映射表的方式，使系统功能的添加和删除变得比较容易。比如要添加一个功能，只需要写一个处理函数，然后在HelloX的内部命令射表内添加一个项目即可。下面我们通过一个示例来说明如何往系统中添加新的功能。
第一步：假设新增的功能命令为mycommand，首先编写一个功能函数，可以直接在SHELL.CPP文件中添加，也可以通过另外的模块实现，然后在SHELL.CPP中，包含实现的命令函数的头文件。假设mycommand命令的实现函数如下。
VOID mycommand(LPSTR)
{
ChangeLine();
PrintLine("Hello,World!");
ChangeLine();
}
该函数的功能十分简单，打印出“Hello,World!”字符串，这也是大多数编程语音的一个入门示例。
第二步：把该命令字符串和命令函数添加到内部命令列表中，并更改CMD_OBJ_NUM宏为原来的值加一，因为新增加了一个内部命令。代码如下（黑体部分是修改内容）：
//#define CMD_OBJ_NUM 21
#defineCMD_OBJ_NUM 22
__CMD_OBJ CmdObj[CMD_OBJ_NUM] = {
{"version" , VerHandler},
{"memory" , MemHandler},
{"sysinfo" , SysInfoHandler},
{"sysname" , SysNameHandler},
{"help" , HlpHandler},
{"cpuinfo" , CpuHandler},
{"support" , SptHandler},
{"runtime" , RunTimeHandler},
{"test" , TestHandler},
{"untest" , UnTestHandler},
{"memview" , MemViewHandler},
{"ktview" , KtViewHandler},
{"ioctrl" , IoCtrlApp},
{"sysdiag" , SysDiagApp},
{"loadapp" , LoadappHandler},
{"gui" , GUIHandler},
{"reboot" , Reboot},
{"poff" , Poweroff},
{"cls" , ClsHandler},
{“mycommand”, mycommand}
};
第三步：重新编译连接（rebuild）整个操作系统核心，并重新制作引导盘引导系统。成功启动后，在命令行提示符下，输入mycommand并回车，就可以看到mycommand的输出了。
需要注意的是，内部命令是直接在shell线程上下文中被调用的，没有自己独立的执行环境。因此只适合于实现较为简单的功能。
以外部命令方式实现应用
外部命令则会有独立的执行上下文，被内核以独立线程方式加载运行。因此，外部命令的功能非常强大，可以进一步以子命令的方式，实现更进一步的功能。比如，HelloX的网络诊断功能，就是以外部命令方式实现的。用户在shell界面下，输入network后回车，即可进入network诊断命令。这时候系统提示符会改变。在network命令下，输入help命令，可以看到该命令模式下所有可用的子命令，如下图：
其中iflist，ping等就是network应用下的子命令。在执行子命令的时候，用户可以指定参数，HelloX会以一种统一的方式，把用户指定的参数，传递给命令处理函数。
下面以network诊断外部命令的实现为例，说明外部命令的实现方式。
第一步：编写外部命令的入口处理函数。
以network命令为例，要编写类似下列形式的处理函数：
DWORD networkEntry(LPVOID p)
{
return Shell_Msg_Loop(NETWORK_PROMPT_STR,CommandParser,QueryCmdName);
}
具体的处理函数的实现，就是开发者大显神通的地方。比如要实现子命令，则需要定义一些子命令映射列表等信息。在上面的实现中，是一个消息处理循环，根据用户的输入，来调用特定的子命令。
注意，外部命令下的子命令，既可以直接在外部命令的线程上下文中执行，也可以单独创建执行线程，取决于开发者的判断。
需要注意的是，外部命令的字命令处理函数，必须以下列格式来定义：
static DWORD ping(__CMD_PARA_OBJ* lpCmdObj)
{
__PING_PARAM PingParam;
ip_addr_t ipAddr;
int count = 3; //Ping counter.
int size = 64; //Ping packet size.
BYTE index = 1;
DWORD dwRetVal = SHELL_CMD_PARSER_FAILED;
__CMD_PARA_OBJ* pCurCmdObj = lpCmdObj;
if(pCurCmdObj->byParameterNum<= 1)
{
return dwRetVal;
}
while(index <lpCmdObj->byParameterNum)
{
if(strcmp(pCurCmdObj->Parameter[index],"/c")== 0)
{
index++;
if(index>= lpCmdObj->byParameterNum)
{
break;
}
count = atoi(pCurCmdObj->Parameter[index]);
}
elseif(strcmp(pCurCmdObj->Parameter[index],"/l") == 0)
{
index++;
if(index>= lpCmdObj->byParameterNum)
{
break;
}
size = atoi(pCurCmdObj->Parameter[index]);
}
else
{
ipAddr.addr= inet_addr(pCurCmdObj->Parameter[index]);
}
index ++;
}
if(ipAddr.addr != 0)
{
dwRetVal = SHELL_CMD_PARSER_SUCCESS;
}
PingParam.count = count;
PingParam.targetAddr =ipAddr;
PingParam.size = size;
//Call ping entry routine.
ping_Entry((void*)&PingParam);
return dwRetVal;
}
子命令处理函数必须返回一个DWORD类型的值，用来表示子命令的执行情况，比如成功或者是失败。同时，子命令处理函数的参数，也必须是__CMD_PARA_OBJ* 类型。这是个内部定义的参数传递数据结构，如下：
typedef struct tag__CMD_PARA_OBJ
{
BYTE byParameterNum; //How many parameters followed.
WORD wReserved;
CHAR* Parameter[CMD_PARAMETER_COUNT];
}__CMD_PARA_OBJ;
byParameterNum指明了这个结构体中包含的参数个数，而Parameter则是一个字符串数组，包含了每个字符串参数的首地址。这与标准的C入口函数main(intargc,char* argv[])的参数是一致的。其中byParameterNum与argc对应，而Parameter则与argv数组对应。需要注意的是，数组中的第一个参数，就是子命令字符串本身。这与C的argv数组中，第一个是应用程序文件名字符串的情况一致。
子命令函数就可以通过分析__CMD_PARA_OBJ对象，来获取每个参数。
第二步：在外部命令数组中，增加入口函数信息。
外部命令数组在kernel/shell/extcmd.c文件中，在这个数组中增加一项，如下：
__EXTERNAL_COMMAND ExtCmdArray[] = {
{"fs",NULL,FALSE,fsEntry},
{"fdisk",NULL,FALSE,fdiskEntry},
{"hedit",NULL,FALSE,heditEntry},
{"fibonacci",NULL,FALSE,Fibonacci},
{"hypertrm",NULL,FALSE,Hypertrm},
{"hyptrm2",NULL,FALSE,Hyptrm2},
#if defined(__CFG_NET_IPv4) || defined(__CFG_NET_IPv6)
{"network",NULL,FALSE,networkEntry},
#endif
//Add your externalcommand/application entry here.
//{"yourcmd",NULL,FALSE,cmdentry},
//The last entry of thisarray must be the following one,
//to indicate theterminator of this array.
{NULL,NULL,FALSE,NULL}
};
数组元素的第一个参数，就是定义的外部命令字符串。用户在shell下，输入该字符串，shell就会以这个字符串为索引，搜索这个数组，找到对应的执行函数，创建一个内核线程并执行。数组元素中的最后一个参数，就是对应的外部命令入口函数。数组元素的第二和第三个参数，主要是指明了外部命令的入口参数，以及是否已阻塞方式执行。如果设置为TRUE，则以非阻塞方式执行，也就是与shell一起并行执行。否则的话，shell会阻塞，等待外部命令执行完毕后，再继续执行。一般设置为FALSE，这样可以确保shell能够及时的释放掉相关资源。
第三步：在帮助数组中增加一行，确保外部命令能够在help输出中可见。
在shell下，用户输入help命令，可以列出系统中所有可用的内部和外部命令。为了确保新增加的外部命令在help命令中可见，需要在下列数组(kernel/shell/shell1.c)中增加相关的帮助描述和输出信息：
//Handler for help command.
DWORD HlpHandler(__CMD_PARA_OBJ* pCmdParaObj) //Command 'help' 's handler.
{
LPSTR strHelpTitle = " The following commands are available currently:";
LPSTR strHelpVer = " version : Print out theversion information.";
LPSTR strHelpMem = " memory : Print out currentversion's memory layout.";
LPSTR strHelpSysInfo =" sysinfo : Print out the system context.";
LPSTR strSysName = " sysname : Change the systemhost name.";
LPSTR strHelpHelp = " help : Print out thisscreen.";
LPSTR strSupport = " support : Print out technicalsupport information.";
LPSTR strTime = " time : Show system date and time.";
LPSTR strRunTime = " runtime : Display the totalrun time since last reboot.";
LPSTR strIoCtrlApp =" ioctrl : Start IO control application.";
LPSTR strSysDiagApp = " sysdiag : System or hardwarediag application.";
LPSTR strFsApp = " fs : File system operating application.";
LPSTR strFdiskApp = " fdisk : Hard disk operating application.";
LPSTR strNetApp = " network : Network diagnostic application.";
LPSTR strLoadappApp = " loadapp : Load applicationmodule and execute it.";
LPSTR strGUIApp = " gui : Load GUI module and enter GUI mode.";
#ifdef __CFG_APP_JVM
LPSTR strJvmApp = " jvm : Start Java VM to run Java Application.";
#endif //__CFG_APP_JVM
LPSTR strReboot = " reboot : Reboot the system.";
LPSTR strCls = " cls : Clear the whole screen.";
PrintLine(strHelpTitle); //Print out the help informationline by line.
PrintLine(strHelpVer);
PrintLine(strHelpMem);
PrintLine(strHelpSysInfo);
PrintLine(strSysName);
PrintLine(strHelpHelp);
PrintLine(strSupport);
PrintLine(strTime);
PrintLine(strRunTime);
PrintLine(strIoCtrlApp);
PrintLine(strSysDiagApp);
PrintLine(strFsApp);
PrintLine(strNetApp);
PrintLine(strFdiskApp);
PrintLine(strLoadappApp);
PrintLine(strGUIApp);
#ifdef __CFG_APP_JVM
PrintLine(strJvmApp);
#endif //__CFG_APP_JVM
PrintLine(strReboot);
PrintLine(strCls);
return S_OK;
}
需要注意的是，不仅仅要增加一个LPSTR(char*)类型的字符串定义，还要在下面增加对应的PrintLine输出，否则不会有信息书出来。
完成上述三个步骤之后，重新编译HelloX内核，然后用最新的内核引导计算机。进入shell后，执行help命令，应该可以看到新增加的外部命令了。输入对应的外部命令字符串，即可看到外部命令的执行结果。
实际上，外部命令的复杂之处，主要还是在于如何处理用户输入，以及如何根据用户的输入，调用对应的子命令处理函数。HelloX实现了很多外部命令，比如本文讲到的network命令，系统诊断sysdiag命令，输入输出控制ioctrl命令，以及文件系统操作命令fs等。开发者可以在这些外部实现的基础上，利用已有的框架，修改特定的部分即可。比如，对于外部命令的入口函数，可以直接在现有的基础上，修改一下函数名。对于子命令处理函数，可以根据需要，进行修改或定义。完成后，要增加到本地子命令映射数组中。比如network命令的子命令映射数组如下：
static struct __NETWORK_CMD_MAP{
LPSTR lpszCommand;
DWORD (*CommandHandler)(__CMD_PARA_OBJ*);
LPSTR lpszHelpInfo;
}SysDiagCmdMap[] = {
{"iflist", iflist, " iflist : Show all network interface(s) insystem."},
{"ping", ping, " ping : Check a specifiedhost's reachbility."},
{"route", route, " route : List all route entry(ies) insystem."},
{"exit", _exit, " exit : Exit theapplication."},
{"help", help, " help : Print out thisscreen."},
{"showint", showint, " showint : Display ethernet interface's statisticsinformation."},
{"assoc", assoc, " assoc : Associate to a specified WiFiSSID."},
{"scan", scan, " scan : Scan WiFi networks andshow result."},
{"setif", setif, " setif : Set IP configurations to a giveninterface."},
{NULL, NULL, NULL}
};
数组元素的第一个参数，就是子命令字符串，第二个参数，是该子命令的处理函数。最后一个字符串信息，则是该子命令的帮助信息。在外部命令提示符下，输入help，就会显示出所有可用的子命令帮助信息。
开发者可以在此基础上，根据自己的实现，修改或删除特定的映射表项即可。
需要注意的是，为了确保整体代码的整洁，建议外部命令的组织，遵循下列原则：
1. 所有新增外部命令的代码，放在一个新创建的代码文件中，不要与现有的shell源文件放在一起；
2. 新增加的外部命令源文件，放在shell目录下。
