实现命令
FreeRTOS-Plus-CLI 为可扩展架构，允许应用程序编写人员定义并注册自身的命令行输入参数。本页介绍如何编写实现命令行为的函数。
函数输入和输出
实现用户定义命令的行为的函数必须具有以下接口（原型）：
BaseType_t xFunctionName( char *pcWriteBuffer,
size_t xWriteBufferLen,
const char *pcCommandString );
以下描述了调用函数时将传递到函数的参数，以及必须返回的值。
参数：
| pcWriteBuffer |
缓冲区，任何生成的输出都应写入其中。例如，如果函数只返回固定的字符串 “Hello World”，则该字符串将写入 pcWriteBuffer。输出必须始终以空字符结尾。 |
| xWriteBufferLen |
pcWriteBuffer 参数所指向的缓冲区大小。将超过 xWriteBufferLen 个字符写入 pcWriteBuffer 后，可能会导致缓冲区溢出。 |
| pcCommandString |
指向整个命令字符串的指针。有了对整个命令字符串的访问权，函数实现就可以提取命令参数（如有）。FreeRTOS-Plus-CLI 提供了接受命令字符串并返回命令参数的辅助函数——因此不需要明确的字符串解析。本页提供了相关示例。 |
返回：
执行某些命令将导致产生不止一行输出。例如，文件系统"dir"（或“Is”）命令将为目录下的每个文件生成一行输出。如果目录下有三个文件，则输出可能如下所示：
file1.txt
file2.txt
file3.txt
为将 RAM 的使用率降至最低，并确定 RAM 的使用率，FreeRTOS-Plus-CLI 允许实现命令行为的函数每次输出一行。函数返回值用于指示输出行是否是输出的末尾，或者是否要生成更多行。
如果生成的输出是输出的末尾，则返回 pdFALSE，这意味着不需再生成更多行，并且命令执行已完成。
如果返回的输出不是输出的末尾，并且在命令执行完成之前仍有一行或多行要生成，则返回 pdTRUE。
再来看一下“dir”命令。在该示例中，此命令输出三个文件名称：
- 实现 dir 命令的函数第一次调用时，可能只输出第一行 (file1.txt)。完成此操作后，该函数须返回 pdTRUE，以指示后面还有更多行。
- 实现 dir 命令的函数第二次调用时，可能只输出第二行 (file2.txt)。完成此操作后，该函数须再次返回 pdTRUE，以指示后面还有更多行。
- 实现 dir 命令的函数第三次调用时，只会输出第三行 (file3.txt)。此时，没有其他行需要输出，因此函数须返回 pdFALSE。
或者，如果有足够多的 RAM，并且 xWriteBufferLen 中传递的值足够大，则可以一次性返回所有三行。在这种情况下，函数须在其第一次执行命令时返回 pdFALSE。
每次执行命令时，FreeRTOS-Plus-CLI 将重复调用实现命令行为的函数，直到函数返回 pdFALSE。
示例
本页提供如下示例：
- 一种命令，该命令不带参数，并且返回单个字符串。
- 一种命令，该命令不带参数并且一次返回单行多个字符串。
- 一种命令，该命令需要固定数量的参数。
- 一种命令，该命令接受可变数量的参数并且一次返回单行可变数量的字符串。
示例 1：不带参数的命令
FreeRTOS vTaskList() API 函数生成一个包含每个任务状态信息的表。该表包含每个任务的单行文本。示例 1 中实现的命令可输出此表。示例 1 演示了一次输出整个表的简单实例。代码中的注释用于进一步解释说明。
static BaseType_t prvTaskStatsCommand( char *pcWriteBuffer,
size_t xWriteBufferLen,
const char *pcCommandString )
{
( void ) xWriteBufferLen;
vTaskList( pcWriteBuffer + strlen( pcHeader ) );
return pdFALSE;
}
Example 1: Outputting multiple lines at once
示例 2 ：一次返回多行
每个用 FreeRTOS-Plus-CLI 注册的命令都有自己的帮助字符串。帮助字符串是演示如何使用命令的一行文本。FreeRTOS-Plus-CLI包含一个“帮助”命令，该命令能返回所有帮助字符串，为用户提供可用的命令列表以及有关如何使用每个命令的说明。示例 2 演示了帮助命令的实现方式。与示例 1 （在该示例中，一次性生成所有输出）不同的是，示例 2 中，一次只生成单行输出。请注意，此函数并非可重入函数。
static BaseType_t prvHelpCommand( char *pcWriteBuffer,
size_t xWriteBufferLen,
const char *pcCommandString )
{
static const xCommandLineInputListItem *pxCommand = NULL;
signed BaseType_t xReturn;
if( pxCommand == NULL )
{
pxCommand = &xRegisteredCommands
}
strncpy( pcWriteBuffer,
pxCommand->pxCommandLineDefinition->pcHelpString,
xWriteBufferLen );
pxCommand = pxCommand->pxNext;
if( pxCommand == NULL )
{
xReturn = pdFALSE;
}
else
{
xReturn = pdTRUE;
}
return xReturn;
}
Example 2: Generating multiple lines of output, one line at a time
示例 3 ：具有固定数量参数的命令
有些命令带参数。例如，文件系统“copy”命令需要带源文件的名称和目标文件的名称。示例 3 是复制命令的架构，用于演示如何访问和使用命令参数。
请注意，如果此命令在注册时声明带有两个参数，除非是固定就提供两个参数，否则 FreeRTOS-Plus-CLI 不会调用此命令。
static BaseType_t prvCopyCommand( char *pcWriteBuffer,
size_t xWriteBufferLen,
const char *pcCommandString )
{
char *pcParameter1, *pcParameter2;
BaseType_t xParameter1StringLength, xParameter2StringLength, xResult;
pcParameter1 = FreeRTOS_CLIGetParameter
(
pcCommandString,
1,
&xParameter1StringLength
);
pcParameter2 = FreeRTOS_CLIGetParameter( pcCommandString,
2,
&xParameter2StringLength );
pcParameter1[ xParameter1StringLength ] = 0x00;
pcParameter2[ xParameter2StringLength ] = 0x00;
xResult = prvCopyFile( pcParameter1, pcParameter2 );
if( xResult == pdPASS )
{
*pcWriteBuffer = NULL;
}
else
{
snprintf( pcWriteBuffer, xWriteBufferLen, "Error during copyrnrn" );
}
return pdFALSE;
}
Example 3: Accessing and using the command parameters
示例 4 ：具有可变数量参数的命令
示例 4 演示了如何创建和实现一个接受可变数量参数的命令。FreeRTOS-Plus-CLI 不会检查所提供的参数的数量，命令的执行只是简单的回传参数，一次一个。例如，如果分配的命令字符串为 "echo_parameters"，则当用户输入
"echo_parameters one two three four"
则生成以下输出结果：
参数为：
1：一
2：二
3：三
4：四
static BaseType_t prvParameterEchoCommand( char *pcWriteBuffer,
size_t xWriteBufferLen, c
onst char *pcCommandString )
{
char *pcParameter;
BaseType_t lParameterStringLength, xReturn;
static BaseType_t lParameterNumber = 0;
if( lParameterNumber == 0 )
{
sprintf( pcWriteBuffer, "The parameters were:rn" );
lParameterNumber = 1L;
xReturn = pdPASS;
}
else
{
pcParameter = ( char * ) FreeRTOS_CLIGetParameter
(
pcCommandString,
lParameterNumber,
&lParameterStringLength
);
if( pcParameter != NULL )
{
memset( pcWriteBuffer, 0x00, xWriteBufferLen );
sprintf( pcWriteBuffer, "%d: ", lParameterNumber );
strncat( pcWriteBuffer, pcParameter, lParameterStringLength );
strncat( pcWriteBuffer, "rn", strlen( "rn" ) );
xReturn = pdTRUE;
lParameterNumber++;
}
else
{
pcWriteBuffer[ 0 ] = 0x00;
xReturn = pdFALSE;
lParameterNumber = 0;
}
}
return xReturn;
}
Example 4: Accessing a variable number of parameters
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.
