yate教程

From：http://yate.null.ro/pmwiki/index.php?n=Main.CppTutorial1

 

Yate可分为两个部分
    * Yate内核
    * Yate模块

    *Yate内核提供基础，辅助API以及消息系统
    *Yate模块使用Yate内核实现特定的功能

Yate模块的类型
Yate模块可分为一下几种
    1.通道
    2.路由器
    3.电话历史记录（Call Detail Recorder）
    4.计费程序
    5.其他模块

如何指定模块的类型
模块类型在这里涉及许多概念性的东西。Yate的设计中并不区分模块的种类，而是根据模块处理的消息类型来区分模块类型。例如一个通道模块接受call.execute消息，并创建一个通道来接受处理它。有此特征的模块我们称之通道模块。另一方面即使如果模块可能接受call.execute消息并处理一个事情，但并不创建一个通道/终端,则它不是一个通道模块。CDRBuilder就是这样的模块。如果你还不清楚，稍等，接下来的例子会说明清楚。

 

程序员眼里的消息
  消息应正确派发到注册了并在监听该消息的模块中。模块可以指定接受消息的优先级。如果一模块监听的call.execute消息优先级为50，其他模块也在监听call.execute消息，但优先级值大于50，则该模块应该先于其他模块获取call.execute消息。一旦接收到该消息，模块可向派发器返回true或fale，并附带一些额外信息。如果返回true，则派发器停止向后续的模块发送消息。返回false，则允许消息按照优先级继续派发到其他模块中。 

  Yate消息不会同Windows消息相混淆，因为他只在Yate系统范围内发送而没有使用操作系统机制发送消息。此外，Yate消息构造是以字符串定义的，而OS消息使用的是数值。

TelEngine命名空间
    所有的Yate API都什么在TelEngine命名空间中，命名空间是C++的一个概念，用于减少程序中变量名和函数名重名冲突。因此，要使
用命名空间TelEngine，如不想写TelEngine::blahblah,你可以使用：

[cpp]  view plain copy

1. using namespace TelEngine;  

 

我们的第一个模块
  我们现在开始写我们的第一个模块，可以接受call.execute消息，并将其呼叫和被叫的号码输出到控制台中。我们设模块名为mymodule1.ln。在这个模块中我们需要讨论以下几个类。
    *Module
    *Message
    *MessageReceiver
    *String
同样还得介绍call.route

CPP文件准备
我们需在模块目录下创建一个名为mymodule1.cpp的文件
包含telengine.h文件则可使用YATE的API

第一步--模块代码
和前面解释的一样，Yate模块要申明他是一个Yate模块都需从Module类派生。Module是从多个类派生的。在Yate API继承关系如下：

[cpp]  view plain copy

1. class YATE_API Module : public Plugin, public Mutex, public MessageReceiver, public DebugEnabler  
2. ...  

 

注意Plugin类向Yate提供了加载模块的功能
在我们的模块中声明类如下：

 

[cpp]  view plain copy

1. class MyModule : public Module  
2. {  
3. public:  
4.     MyModule()  
5.         : Module("MyModule1","misc"), m_init(false) {}  
6.     virtual void initialize();  
7.     virtual bool received(Message &msg,int id);  
8. private:  
9.     enum  
10.     {  
11.         CallRoute = Private + 1  
12.     } PrivateRelayID;  
13.     bool m_init;  
14. };  

 

第二步：创建Module类的静态变量
当Yate模块加载一个模块是，他首先会在模块中（Plugin）查找名为_plugin的静态变量。在我们的例子中，我们需要定义类MyModule（派生于Plugin）的一个静态变量。Yate提供了帮助做这个，仅需要这样使用：

[cpp]  view plain copy

1. INIT_PLUGIN(MyModule);  

 

第三步：模块initialize()的重要性
你需特别注意到我们在MyModule声明定义的initialize方法。initialize函数在Plugin类是虚函数，在Yate加载模块时会被调用。MyModule需要重载它，做一些模块初始化工作。通常在这里注册模块想监听的消息。我们可这样写代码：

[cpp]  view plain copy

1. void MyModule::initialize()  
2. {  
3.     Output("Initializing module mymodule1");  
4.     if(!m_init) {  
5.     m_init = true;  
6.     }  
7. }  

Yate提供的Output函数输出信息到控制台。它只在必要的时候使用。Yate同样提供了一些其他API函数将调试信息输出到控制台。

第四步：添加代码接受消息
模块通常需要接受一个或多个消息。模块接受到一个消息并执行程序制度的工作。Module类派生与MessageReceiver，MessageReceiver通过虚函数received()提供了接受消息能力。我们可按自己爱好添加代码接受消息，像这样：

[cpp]  view plain copy

1. void MyModule::initialize()  
2. {  
3.     Output("Initializing Module mymodule1");  
4.     if(!m_init) {  
5.     Engine::install(new MessageRelay("call.route",this,CallRoute,55));  
6.     m_init = true;  
7.     }  
8. }  

 

Yate中的类Engine。Yate创建了一个Engine的静态对象作为他（Yate）的启动（不是模块的启动）。这个类启动真个Yate的服务器/服务。这个类全是静态成员函数。Install()同样是静态函数，这也就是我们为什么Engine::install这样调用的原因。install向yate提供了我们的MessageRelay类对象，指定了我们想要监听消息的消息id、监听优先级等。第三个参数CallRoute是枚举值，它仅指定我们想关联消息的消息ID。枚举值CallRoute为Private+1，在类Module中定义，用于指定（说明）该消息在模块中没有任何RelayID。可看看Yate中Module类的枚举值。当你监听到多个消息，你需要识别监听到的消息，当然这有多种方式实现。注意在MessageRelay的最好一个参数值为55，这说明我们想监听的消息优先级别值为55。因此如果其他模块也在监听同样的消息且优先级更高，将先接收到这个消息并且如果他返回非ture,我们的这个模块才能接受到这个消息。MessageRelay被Yate用例发送消息，它的构造函数拥有一个MessageReceiver类的对象用户消息的通知。我们MyModule继承于Module，而Module继承于MessageReceiver，因此，我们在MyModule可提供这个对象（MessageReceiver）。

第五步：重载received

类MessageReceiver的received(Message &msg,int id)方法由Yate调用，用于派发注册过监听的消息。received在MessageReceiver中声明为虚函数。注意，返回值为bool，如果处理完这个消息，并不想后面的模块接受处理该消息，返回true。希望后续的模块继续处理该消息返回false即可。这里（received）我们可以添加自己的逻辑代码。在received中我们可写一些代码，在call.route消息来临时，输出呼叫者和被呼叫者名。

[cpp]  view plain copy

1. bool MyModule::received(Message &msg,int id)  
2. {  
3.     String called,caller;  
4.     called = msg.getValue("called");  
5.     caller = msg.getValue("caller");  
6.     Output("mymodule1: call.route called  
7.     caller %s, and called %s",caller.c_str(),called.c_str());  
8.     return false;  
9. }  

 

上述代码使用了Yate API提供的String类。从名可知这个类提供了字符串的相关操作。Message继承与NamedList，这是YATE提供的另一个类，用于更好管理字符串与字符串直接的映射链表。类NamedList的函数getValue()，我们先获取被叫号码(熟知的DNID)，然后获取呼叫者的号码，作为电信运营商的ANI/CLI（被叫者ID/呼叫者ID）。c_str为String的成员函数，返回字符串存储的数据，类型为const char*.

[cpp]  view plain copy

1. #include <yatengine.h>  
2. #include <yatephone.h>  
3. #include <stdio.h>  
4. #include <stdlib.h>  
5. using namespace TelEngine;  
6. class MyModule : public Module  
7. {  
8. public:  
9.     MyModule()  
10.         : Module("MyModule1","misc"), m_init(false) {}  
11.     virtual void initialize();  
12.     virtual bool received(Message &msg,int id);  
13. private:  
14.     enum  
15.     {  
16.         CallRoute = Private + 1  
17.     } PrivateRelayID;  
18.     bool m_init;  
19. };  
20. bool MyModule::received(Message &msg,int id)  
21. {  
22.     String called,caller;  
23.     called = msg.getValue("called");  
24.     caller = msg.getValue("caller");  
25.     Output("mymodule1: call.route called  
26.     caller %s, and called %s",caller.c_str(),called.c_str());  
27.     return false;  
28. }  
29. void MyModule::initialize()  
30. {  
31.     Output("Initializing Module mymodule1");  
32.     if(!m_init) {  
33.         Engine::install(new MessageRelay("call.route",this,CallRoute,55));  
34.         m_init = true;  
35.     }  
36. }  
37. INIT_PLUGIN(MyModule);  
38. /* vi: set ts=8 sw=4 sts=4 noet: */