FreeSwitch ESL——Event Object,Connect Object(事件套接字的事件对象及连接对象）

Event Object

 

new

语法：

new($event_type [, $event_subclass])

作用：实例化一个新的事件对象，以便于使用以下的方法。

 

serialize

语法：

serialize([$format])

作用：将事件转化为冒号分割形如”name:value”的键对。$format的值可以为：

1.      “xml“

2.      “json”

3.      “plain”(default)

 

setPriority

语法：

setPriority([$number])

作用：设置事件的优先级

 

getHeader

语法：

getHeader($header_name)

作用:根据一个事件对象中的$header_name来获取头部值

 

getBody

语法：

getBody()

作用：获得事件对象的正文

 

getType

语法：

getType()

作用：获得事件对象的类型

 

addBody

语法：

addBody($value)

 

作用：将$value添加到事件对象的正文中。该对象可能在同一个事件对象中被多次调用

 

addHeader

语法：

addHeader($header_name, $value)

作用：向事件对象中添加一对值到头域中。该对象可能在同一个事件对象中被多次调用

 

delHeader

语法:

delHeader($header_name)

作用：在事件对象中删除名字叫$header_name的头域

 

firstHeader

语法：

firstHeader()

作用：将指针设置为指向事件对象的一个头域，并且返回第一个头域的键值。该函数必须在nextHeader对象调用前调用

 

nextHeader

语法：

nextHeader()

作用：将指针指向事件对象的下一个头域，并返回它的键值。调用它之前必须先调用firstHeader来设置指针!若当前位置已经是头域的最后一个节点，则调用该函数后将指向NULL

 

 

Connection Object

new

语法1：

new($host, $port, $password)

语法2：

new($fd)

作用：根据一个已存在的套接字句柄初始化一个ESL连接对象实例。

仅在Outbound(FreeSwitch作为客户端)模式下有效。即使在inbound模式下传递一个有效的套接字句柄也是无效的。

作用：初始化一个ESL连接对象实例。后面三个参数分别为主机名、端口号、密码。

 

该函数仅在inbound模式（FreeSwitch作为服务端）下有效。换而言之，该函数的目的是创建一个连接至FreeSWITCH的对象，并且它并未绑定到任何的呼叫或者信道上。

它并没有初始化通道信息（因为inbound连接并未绑定到任一个信道上）。简单来说，如果调用getInfo()函数永远返回NULL。

 

socketDescriptor

语法：

socketDescriptor()

作用：如果连接对象已连接，则返回该连接对象的UNIX文件描述句柄（FD）。

 

connected

语法：

connected()

作用：测试连接对象是否已连接。已连接则返回1，否则返回0

 

getInfo

语法：

getInfo()

作用：当FreeSwitch在outbound模式下连接时，它将在初始化阶段首先发送”CHANNEL_DATE”事件。该函数将返回跟该对象相关的信道信息。

当FreeSwitch在inbound模式下，将返回NULL

 

send

语法：

send($command)

作用：发送一个命令至FreeSwitch

它不会等待一个应答，而需要调用recvEvent或者recvEventTimed来循环等待接受事件。该应答将包含一个叫“content-type”的头域，该头域包含”api/response”或者“command/reply”的值。

为了自动等待应答事件，可以使用sendRecv()代替。

 

sendRecv

语法：

sendRecv($command)

作用：sendRecv($command)在调用的时候，会先调用send($command)，然后在调用recvEvent()，然后返回一个ESL事件的实例。

recvEvent()会在一个循环中调用并一直阻塞知道收到一个头域包含”api/response”或者“command/reply”的值，然后再返回ESL事件对象实例。

在此期间收到的所有事件将保存到一个内部队列中，这些事件可以在后续的recvEvent()中取到。

 

api

语法：

api($command[, $arguments])

作用：向FreeSWITCH服务器发送一个API命令，这个命令将处于阻塞状态直到命令执行结束。

api($command,$args)等效于sendRecv(“api$command $args)

 

bgapi

语法：

bgapi($command[, $arguments][,$custom_job_uuid])

作用：向FreeSWITCH服务器发送一个后台API命令，该命令将在它自己的线程中执行。

bgapi($command,$args)等效于sendRecv(“bgapi$command $args)。

 

sendEvent

语法：

sendEvent($send_me)

作用：向FreeSwitch发送一个事件。

 

recvEvent

语法：

recvEvent()

作用：向FreeSwitch返回一个接收到的事件。如果接收到事件，该函数在处于阻塞状态，知道新事件来临。

如果在呼叫期间sendRecv()队列中有事件，那么队列中的第一个事件将被返回，并从队列中删除。换句话说，在连接中事件可以被读取。

 

recvEventTimed

语法：

recvEventTimed($milliseconds)

作用：类似于recvEvent()，但是它会阻塞$milliseconds毫秒.

如果将参数设置为0那么它将会立即返回，这个特性在轮询中特别有用。

 

filter

语法：

filter($header, $value)

作用：用于安装一个过滤器。该过滤器是对输入过滤，而不是对输出过滤。即符合条件的才能进入系统。

 

events

语法：

events($event_type,$value)

作用：$event_type的值可以为”plain“或者”xml”，其他任何输入都将被解释为”plain”

如果要调用myevents(event的一个特殊情况，用于outbound模式中)必须使用sendRecv(“myevents”)来调用，千万用events来调用。

 

execute

语法：

execute($app[, $arg][, $uuid])

作用：执行一个拨号计划的应用，并且等到从服务器发送过来的应答。套接字的连接不是固定在一个信道上（大部分情况下为inbound模式），三个参数都是必要的，其中uuid指明了为app指明了信道信息。

该函数将返回一个包含应答的ESL事件对象。通过getHeader(‘Reply-Text”)可以取出应答值。如果应答值为”+OK[Success Message]则表示成功，“-ERR [Error Message]表示失败。

可以通过以下的例子看看当调用excuse()命令后如何获取uuid。

 

在inbound模式下，可以根据以下命令获得一个新的uuid

$uuid = $esl->api("create_uuid")->getBody();

在outbound模式下，可以根据以下命令获得

$uuid = $esl->getInfo()->getHeader("unique-id")

 

 

executeAsync

语法：

executeAsync($app[, $arg][, $uuid])

作用：和execute一样，但是它在等待服务器应答的时候不会阻塞。其实这个函数本质上也是调用了execute()函数，只不过增加了”async:true”的头而已。

 

setAsyncExecute

语法：

setAsyncExecute($value)

作用：强制将套接字连接设置为异步模式。该命令在outbound模式下不起作用。

$value为1表示强制开启异步模式，0为同步模式。

特别要注意的是，调用setAsysncExecute(1)的本质就是调用带“asysnc:true”头的execute()函数。其他套接字路由不受此设置的影响。

 

setEventLock

语法：

setEventLock($value)

作用：强制让套接字连接打开同步模式。这个命令在outbound模式不起作用，因为在dialplan中没有将它设置为异步模式，因为这些连接已经处于同步模式了。

$value为1表示打开同步模式，0表示不强制打开。

要注意的是，调用setEventLock(1)的操作等价于调用带”event-lock:true”头的execute()函数。其他的事件套接字路由不受此设置的影响。

 

disconnect

语法：

disconnect()

作用：关闭连接

 

freeSwitch1.4版本（2014-02-16后的master版本）的C语言调用示例如下

 

int main(void)
{
        char *private_data = "some private string or struct ...";
        esl_global_set_default_logger(7);
        esl_listen_threaded("localhost", 8040, mycallback, private_data, 100000);
        return 0;

}

Event Socket Command翻译出处：http://wiki.freeswitch.org/wiki/Event_Socket

其他翻译出处：https://freeswitch.org/confluence/display/FREESWITCH/Event+Socket+Library