FreeRTOS_CLI.h

BaseType_t FreeRTOS_CLIRegisterCommand( CLI_Command_Definition_t *pxCommandToRegister )

FreeRTOS-Plus-CLI 是一个可扩展的框架， 应用程序写入器可以通过该框架定义并注册自己的命令行输入命令。实现用户自定义命令行为的函数必须使用一个特定的接口， 如单独页面的描述所示。
本页介绍了FreeRTOS_CLIRegisterCommand()，它是用于向 FreeRTOS-Plus-CLI 注册命令的 API 函数。注册命令的方法是将实现命令行为的函数与文本字符串关联起来， 并将关联情况告知 FreeRTOS-Plus-CLI。然后，FreeRTOS-Plus-CLI 将在每次输入命令文本字符串时自动运行该函数。读完这一页你就会明白。

注意：代码中出现的FreeRTOS_CLIRegisterCommand()原型是一个指向CLI_Command_Definition_t类型常量结构体的常量指针。此处删除了常量限定符， 以使原型更易于阅读。

参数：

• pxCommandToRegister
  正在注册的命令，由CLI_Command_Definition_t类型的结构体定义。该结构体如此表下方所示。

返回：

• 如果命令成功注册，则返回pdPASS。
• 如果由于没有足够的FreeRTOS 堆可用于创建新列表项而导致命令无法注册，则返回pdFAIL。

CLI_Command_Definition_t

命令由CLI_Command_Definition_t类型的结构体定义， 结构体如下所示。代码中的注释描述了结构体成员。

typedef struct xCLI_COMMAND_DEFINITION
{
    /* 命令行输入字符串。这是用户在运行命令时输入的字符串。例如，FreeRTOS-Plus-CLI 
       help函数使用字符串“help”。如果用户输入“help”，则执行help命令。 */
    const char * const pcCommand;

    /* 描述命令及其预期参数的字符串。这是执行help命令时输出的字符串。字符串必须以
       命令本身开始，以“\r\n”结束。例如，help命令本身的help字符串是：
       "help: Returns a list of all the commands\r\n" */
    const char * const pcHelpString;

    /* 指向实现命令行为的函数的指针（实际上是函数名）。 */
    const pdCOMMAND_LINE_CALLBACK pxCommandInterpreter;

    /* 命令所需的参数数量。FreeRTOS-Plus-CLI只会在命令行中输入的参数数量与此数量匹配
	   时执行该命令。*/
    char cExpectedNumberOfParameters;

} CLI_Command_Definition_t;

CLI_Command_Definition_t 结构体

示例

一种 FreeRTOS-Plus-CLI 特色演示实现了文件系统 “del” 命令。命令定义如下。

static const CLI_Command_Definition_t xDelCommand =
{
    "del",
    "del <filename>: Deletes <filename> from the disk\r\n",
    prvDelCommand,
    1
};

文件系统 del 命令的定义

注册此命令后：

• 每次用户键入“del”时都会执行 prvDelCommand()。
• 输出”del <filename>: Deletes <filename> from the diskrn”来描述用户键入“help”时的del命令。
• del 命令需要一个参数（被删除文件的名称)。如果输入参数的数量不是1，FreeRTOS-Plus-CLI将输出错误字符串，而不是执行prvDelCommand()。

然后使用以下函数调用向 FreeRTOS-Plus-CLI 注册 del 命令：

FreeRTOS_CLIRegisterCommand( &xDelCommand );

使用 FreeRTOS-Plus-CLI 注册 xDelCommand 结构体