Asterisk模块编写3

昵称7719523 2011-09-15

展开全文

面是通过基本接口来为Asterisk提供更多功能系列文章的第三篇--Asterisk模块编写3--高级。
第一篇《Asterisk模块编写1--入门》
第二篇《Asterisk模块编写2--进阶》
      在本文里，你将看到如何实现一个Asterisk CLI命令。CLI命令对于显示配置信息、统计信息和其它调试目的来说都是非常有用的。我们继续编辑上一篇文章中的那个res_helloworld2.c。
      第一步是加载定义CLI命令接口的头文件：
#include "asterisk/cli.h"
      下面是实现CLI命令“echo”的代码，简单地打印了CLI命令的第一个参数，后面会解释这个功能。

复制代码

static char *handle_cli_echo(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
{
switch (cmd) {
case CLI_INIT:
e->command = "echo";
e->usage =
"Usage: echo <stuff>\n"
" Print back the first argument.\n"
"Examples:\n"
" echo foo\n"
" echo \"multiple words\"\n"
"";
return NULL;
case CLI_GENERATE:
return NULL;
}
if (a->argc == e->args) {
ast_cli(a->fd, "You did not provide an argument to echo\n\n");
return CLI_SHOWUSAGE;
}
ast_cli(a->fd, "%s\n", a->argv[1]);
return CLI_SUCCESS;
}

        这个CLI处理程序相匹配的CLI命令处理程序定义的函数原型。ast_cli_entry参数包括有关CLI命令正在执行的静态信息。当CLI命令非正常执行其他调用的时候，会设置cmd参数。该ast_cli_args参数包含这一命令一次执行的特定信息，如同命令参数。
                static char *handle_cli_echo(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)

        在函数的开头switch语句是用来处理cmd参数，以指示调用什么功能。有两种情况需要处理：

CLI_INIT. 每个CLI命令处理程序都要执行一次 CLI_INIT. 用来要求函数说明命令是什么，用法是什么等。
CLI_GENERATE. This cmd is used for implementing tab completion. CLI commands that provide tab completion of arguments must add code here. Implementing tab completion may be explained in a later tutorial. For now, there are many examples throughout the code.

        下面这小段代码表示至少给函数提供了一个参数。值得注意的是，这里的ast_cli_entry参数用于检索多少命令本身定义的参数和ast_cli_args参数用于检索多少参数，实际上是在CLI命令行下执行此命令时指定的。如果它们相等，那么就能提供简单的“echo”。
        if (a->argc == e->args) {
                ast_cli(a->fd, "You did not provide an argument to echo\n\n");
                return CLI_SHOWUSAGE;
        }
        最后，我们打印一个参数到CLI，返回 CLI命令成功执行的结果。
        ast_cli(a->fd, "%s\n", a->argv[1]);
        return CLI_SUCCESS;
        下一步增加包含在这个模块里的CLI命令表。我们将使用 AST_CLI_DEFINE() 为表增加单个入口。 AST_CLI_DEFINE 包含了CLI 命令处理函数的指针，以及这个命令时用来做什么的总结。
        static struct ast_cli_entry cli_helloworld[] = {
                AST_CLI_DEFINE(handle_cli_echo, "Echo to the CLI"),
        };

        最后，就像我们在前面文章中提到的那样，我们要修改 load_module 和unload_module来把CLI命令表注册到Asterisk内核里。
        卸载模块unload_module，加入：
                ast_cli_unregister_multiple(cli_helloworld, ARRAY_LEN(cli_helloworld));
        加载模块load_module，加入：
                ast_cli_register_multiple(cli_helloworld, ARRAY_LEN(cli_helloworld));
        就这样，重新编译安装这个模块，完整的代码请参见这个文件 res_helloworld3.c 。
        然后您可以试试这个模块了：

复制代码

*CLI> help echo
Usage: echo
Print back the first argument.
Examples:
echo foo
echo "multiple words"
*CLI> echo
You did not provide an argument to echo
Usage: echo
Print back the first argument.
Examples:
echo foo
echo "multiple words"
*CLI> echo foo
foo
*CLI> echo hello world
hello
*CLI> echo "hello world"
hello world

翻译的比较拗口，勉强看吧，为方便对照，下面是英文全文。

How-to: Write an Asterisk Module, Part 3
作者/ Russell Bryant     摘自 http://www./blog/
In this section, you will see how to implement an Asterisk CLI command. CLI commands are extremely useful for showing configuration, statistics, and other debugging purposes.
We are going to continue editing the module from part 2, res_helloworld2.c.
The first step is to include the header file which defines the CLI command interface.

#include "asterisk/cli.h"

Here is the code for a CLI command, “echo”. It simply prints back the first argument to the CLI command. The individual parts of this function will be described later.
static char *handle_cli_echo(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
{
    switch (cmd) {
    case CLI_INIT:
        e->command = "echo";
        e->usage =
            "Usage: echo <stuff>\n"
            "       Print back the first argument.\n"
            "Examples:\n"
            "       echo foo\n"
            "       echo \"multiple words\"\n"
            "";
        return NULL;
    case CLI_GENERATE:
        return NULL;
    }

    if (a->argc == e->args) {
        ast_cli(a->fd, "You did not provide an argument to echo\n\n");
        return CLI_SHOWUSAGE;
    }

    ast_cli(a->fd, "%s\n", a->argv[1]);

    return CLI_SUCCESS;
}

The first line of this CLI handler matches the defined function prototype for CLI command handlers. The ast_cli_entry argument includes static information about the CLI command being executed. The cmd argument is set when the CLI command is being invoked for a reason other than normal execution from the CLI, which will be explained more later. The ast_cli_args argument contains information specific to this one time execution of the command, like the arguments to the command.

static char *handle_cli_echo(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)

The switch statement at the beginning of the function handles when the cmd argument is set to indicate that the function is being called for a reason other than normal execution. There are two cases handled.

CLI_INIT. Every CLI command handler is called one time with a cmd of CLI_INIT. This asks the function to fill in the documentation on what the command is, as well as usage documentation.
CLI_GENERATE. This cmd is used for implementing tab completion. CLI commands that provide tab completion of arguments must add code here. Implementing tab completion may be explained in a later tutorial. For now, there are many examples throughout the code.

The next code snippet ensures that at least one argument has been provided to the function. It is worth noting here that the ast_cli_entry argument is used to retrieve how many arguments define the command itself and the ast_cli_args argument is used to retrieve how many arguments were actually specified at the CLI when executing this command. If they are equal, then simply “echo” was provided.

if (a->argc == e->args) {
ast_cli(a->fd, "You did not provide an argument to echo\n\n");
return CLI_SHOWUSAGE;
}

Finally, we print a single argument to the CLI, and return that the execution of the CLI command was successful.

ast_cli(a->fd, "%s\n", a->argv[1]);
return CLI_SUCCESS;

The next thing that we have to add is the table of CLI commands included in this module. We will use AST_CLI_DEFINE() to add a single entry to this table. AST_CLI_DEFINE includes the pointer to the CLI command handling function, as well as a brief summary of what the command does.

static struct ast_cli_entry cli_helloworld[] = {
AST_CLI_DEFINE(handle_cli_echo, "Echo to the CLI"),
};

Finally, as discussed in part 2, we have to modify load_module and unload_module to register and unregister the CLI command table with the Asterisk core.
In unload_module, we add this:

ast_cli_unregister_multiple(cli_helloworld, ARRAY_LEN(cli_helloworld));

In load_module, we add this:

ast_cli_register_multiple(cli_helloworld, ARRAY_LEN(cli_helloworld));

That’s it! Recompile and reinstall the module. Take a look at res_helloworld3.c, for the completed code.
You can then try it out.
*CLI> help echo
Usage: echo
       Print back the first argument.
Examples:
       echo foo
       echo "multiple words"

*CLI> echo
You did not provide an argument to echo

Usage: echo
       Print back the first argument.
Examples:
       echo foo
       echo "multiple words"

*CLI> echo foo
foo

*CLI> echo hello world
hello

*CLI> echo "hello world"
hello world