freeswitch 权威指南 --- 高级篇

官网文档：https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/

关于 freeswitch 的公开教程：https://zhuanlan.zhihu.com/p/451981734

内容来自《FreeSWITCH 权威指南》：目录：https://juejin.cn/post/7020580794829635591

代码下载：https://book.dujinfang.com/download.html

1、客户端和开发接口

基于 FreeSWITCH 的开发一般有四种方式：后两种方法需要熟悉FreeSWITCH的源代码

1. 使用嵌入式脚本在 FreeSWITCH 内部灵活地控制呼叫流程，以及通过共享数据库或简单API 等与现有业务系统集成；
1. 使用 Event Socket 在外部程序中控制呼叫流程，控制更灵活，与其他系统更容易集成；
1. 直接在FreeSWITCH中修改现有代码，或通过添加新模块以扩展FreeSWITCH的现有功能，并能结合前两种方式创建更强大的应用；
1. 将FreeSWITCH的底层库 libfreeswitch 嵌入到其他系统中，这样被嵌入的用系统中就瞬间增加了 FreeSWITCH 的全部功能，这种方法用得比较少。

FreeSWITCH 默认使用 XML Dialplan 配置呼叫流程。XML 文件描述性很强，因而也可以描述比较复杂的呼叫流程。但在一些比较高级的 IVR 应用和呼叫交互流程中，仅靠简单的 XML 的配置很难满足要求。因而还需要更灵活、更强大的解决方案。除 XML Dialplan外，FreeSWITCH 支持使用嵌入式的脚本语言控制呼叫流程。不仅可以用它们写出灵活多样的 IVR，给用户带来更好的体验，

在内部，FreeSWITCH 通过使用 swig 工具来支持多种开发语言。简单来讲，swig 是一个包装工具（Wrapper），它可以将 FreeSWITCH 用C语言实现的一些功能包装成各种其他语言的接口、类或者方法，这样就可以在使用其他语言时以原生的方式调用。现在已知支持的语言有 C、Perl、PHP、Python、Ruby、Lua、Java、Tcl 以及由 Managed 支持的 .Net 平台语言，如 C#、VB.NET等。FreeSWITCH 源代码中的 swig 脚本和程序已被转换成各种语言的接口了，因而开发者不需要安装 swig 工具就可以使用。不过 JavaScript 语言比较特殊一些，对它的支持是基于Google 的V8库，在 mod_v8 模块中实现的。

理论上讲，可以使用任何语言，只要该语言支持 TCP Socket 就行。

SWIG 官网：http://www.swig.org

SWIG 简介、安装、使用方法：https://blog.csdn.net/qq_41185868/article/details/103558686

SWIG：Python 调用 C++：https://zhuanlan.zhihu.com/p/462193340

XML Dialplan 已经体现了其非凡的配置能力，它配合 FreeSWITCH 提供的各种 App 使用时，也可以认为是一种脚本。当然，毕竟 XML 是一种描述语言，功能还比较有限，为了扩展其功能，FreeSWITCH 通过嵌入其他语言的解析器支持很多流行的编程语言。这些语言一般都能提供if...else 判断及等循环跳转控制等，因而控制呼叫流程更加灵活。

Lua ELS 开发

FreeSWITCH Lua脚本：https://www.cnblogs.com/garvenc/p/freeswitch_learning_lua.html

Lua 因其优雅的语法及小巧的身段受到很多开发者的青睐，尤其是游戏开发人员。FreeSWITCH 中 Lua 模块是默认加载的。在所有嵌入式脚本语言中，Lua 是最值得推荐的语言。首先它非常轻量级，mod_lua.so 经过减肥（Strip）后只有272KB；另外，它的语法相对的简单。有人做过对比，在嵌入式的脚本语言里，如果Python得2分，Perl得4分，JavaScript得5，则Lua语言可得10分。另外，Lua模块的文档也是最全的。

Lua 官网：https://www.lua.org/

Lua 下载：https://www.lua.org/download.html

Lua 教程：https://www.runoob.com/lua/lua-tutorial.html

Lua与JS（JavaScript的缩写，下同）有很多相似的地方，简述如下。

变量无需声明。 Lua与JS都是"弱"类型的语言（不像C），不需要事先声明变量的类型。
区分大小写。 Lua和JS都是区分大小写的。true和false分别代表布尔类型的真和假，
函数可以接受个数不定的参数。与JS类似，在Lua中，与已经声明的函数参数个数相比，实际传递的参数个数可多可少
哈希可以用方括号或点方式引用。
数字区别不大。在JS和Lua中，整数和浮点数是没有区别是的。它们在内部都是以浮点数表示。在Lua中，所有的数字类型都是number类型。
分号是可选的。
默认全局变量。在JS中，如果用var声明一个变量并赋值，则它是本地变量；如果不用var声明，默认就是全局的
使用双引号和单引号表示字符串。
函数是一等公民。在JS和Lua中，函数是一等公民，这意味着，你可以将它赋值给一个变量，将它作为参数传递，或者直接加上括号进行调用。
函数都是闭包。在JS和Lua中，函数都是闭包。简单来说，这意味着函数可以随时访问该函数在定义时可以访问的本地变量，尽管在以后调用时这些本地变量逻辑上已经"失效"了。

将电话路由到Lua脚本：originate user/1000 &lua(test.lua)

lua是一个App，它的参数就是脚本的名字，脚本的默认路径在安装路径的scripts目录下，当然你也可以指定一个绝对路径，如/tmp/test.lua。在Dialplan XML中，使用下列配置便可将进入Dialplan的电话（Channel）交给Lua脚本接管。<action application="lua" data="test.lua"/>

除此之外，也可以直接使用uuid_transfer命令直接配合inline Dialplan将一个Channel路由到Lua脚本，如：uuid_transfer <uuid> lua:/tmp/test.lua inline

总之，这里的Lua是一个标准的App，在任何可以使用App的地方都可以使用它（如上面介绍的各种场景，以及后面要介绍的Event Socket等。甚至在Lua脚本中也可以再次使用lua App来调用下一个Lua脚本）。

Session 相关函数

在Lua环境中，FreeSWITCH会自动生成一个session对象（实际上是一个Table），因而可以在Lua脚本中使用Lua类似面向对象的语法特性编程，如以下脚本放播放欢迎声音

Lua 复制代码

--
session:answer()
--
session:sleep(1000)
--
session:streamFile("/tmp/hello-lua.wav")
--
session:hangup()

大部分与Session有关的函数都是跟FreeSWITCH中的App是一一对应的，如上面的answer、hangup等。有一点要特别说明：streamFile对应playback这个App。如果在Lua中没有对应的函数，也可以通过session:execute()函数来执行相关的App，如session:execute("playback","/tmp/sound.wav") 与 session:streamFile("/tmp/sound.wav") 是等价的

需要注意，Lua脚本执行完毕后默认会挂断电话，所以上面的Hello Lua例子中不需要明确的session:hangup()。如果想在Lua脚本执行完毕后继续执行Dialplan中的后续流程，则需要在脚本开始处先设置不要自动挂机，语法如下：session:setAutoHangup(false)

例如下列场景，test.lua执行完毕后（假设没有session:hangup()，主叫也没有挂机），如果没有setAutoHangup(false)，则后续的playback动作得不到执行。

XML 复制代码

<extension name="test-lua">
	<condition field="destination_number" expression="^1234$">
		<action application="answer"/>
		<action application="lua" data="test.lua"/>
		<action application="playback" data="lua-script-complete.wav"/>
	</condition>
</extension>

与 Ssession 相关的几个常用的函数：

getVariable。取得变量的值
getUUID。取得当前Session的UUID
local uuid = session:get_uuid(]); 等价于 local uuid = session:getVariable("uuid")
setVariable。设置通道变量，等价于Dialplan App里的set：session:setVariable("varname", "varval")
hangup。挂断当前通话。session:hangup(); 或者 session:hangup("USER_BUSY")
ready。检查Session是否可正常使用，如果已经挂机就会返回false。在写脚本时，如果有循环，一定需要经常检测session:ready()是否为true，否则Session挂机后Lua脚本可能仍然在死循环地运行。
streamFile：放音，相当于Dialplan App里的playback。session:streamFile("/tmp/test.wav")
recordFile：录音，相当于Dialplan App里的record，参数是：file_name [,max_len_secs] [,silence_threshold] [,silence_secs]
其中，各参数含义如下：
file_name：录音文件名。
max_len_secs：录音最长的秒数。
silence_threashold：一个声音阈值，如果声音小于该值，就认为是静音。
silence_secs：如果静音时长大于一定秒数，则停止录音。
例如，以下函数将对当前的Channel录音，并存放到/tmp/test_record.wav中：
session:recordFile("/tmp/test_record.wav")
read。类似于Dialplan App中的read，用于播放一个声音并获取DTMF。它的5个参数与read含义相同：<min digits><max digits><file to play><inter-digit timeout><terminators>
digits = session:read(15, 18, "/tmp/input-id-card.wav", "5000", "#");
session:("log", "INFO ID Card Number: ".. digits .."\n"); 可以发现Lua中的read比Dialplan App中的read少了一个参数。由于session:read()能返回值，因此那个参数就不需要了，实际收到的 DTMF 会返回到本例的 digits 变量中。
playAndGetDigits。与Dialplan App中的play_and_get_digits类似，它的参数格式是：<min_digits>, <max_digits>, <max_attempts>, <timeout>, <terminators>,<prompt_audio_files>,<input_error_audio_files>,<digit_regex>, [variable_name], [digit_timeout], [transfer_on_failure]) 其中，大部分参数都很直观，也跟play_and_get_digits中类似。其中timeout是收齐所有号的超时值，而digit_timeout是允许的两次按键之音的时间间隔最大值，最后transfer_on_failure指明如果失败后是否转到Dialplan中的一个Extension上去，它的格式应该是一个Dialplan三要素的格式串，如"failed XML dialplan"。
重写如下：
digits = session:playAndGetDigits(15, 18, 3, 10000, "#",
"/tmp/input-id-card.wav", "/tmp/invalid_num.wav",
"^\\d{15}|\\d{17}[0-9\\*]$")
session:execute("log", "INFO ID Card Number: ".. digits .."\n");
setInputCallback。在放音或录音时，用户按下的DTMF可以用于触发一些功能。所以在这些状态下，Lua支持如果收到DTMF等外部输入时，则调用相关的回调函数。setInputCallback的作用就是设置（安装）一个回调函数。

更多与Session相关的函数可以参考相关的wiki文档：http://wiki.freeswitch.org/wiki/Mod_lua

非Session函数、独立的Lua脚本

Lua脚本中也可以使用跟Session不相关的函数，最典型的是freeswitch.consoleLog()，其用于输出日志，如：freeswitch.consoleLog("NOTICE", "Hello lua log!\n")

另外一个是freeswitch.API()，允许你在Lua中执行任意API，如：a.lua

api = freeswitch.API()

reply = api:execute("version", "")

freeswitch.consoleLog("INFO", "Got reply:\n\n" .. reply .. "\n")

上面 Lua 脚本可以直接在 FreeSWITCH 控制台上执行：freeswitch> lua /tmp/a.lua

除此之外，其他的非 Session 函数还有 freeswitch.bridge()、freeswitch.email() 等，

非Session函数一般运行在独立的Lua脚本中。独立的Lua脚本可以直接在控制台终端上执行（使用luarun），这种脚本大部分可用于执行一些非Session相关的功能（因为这里面没有Session）。读到这里读者已经了解到了，Lua是一个App，而luarun是一个API。

上面的 a.lua 就是一个典型的可独立运行的Lua脚本。独立运行的Lua脚本跟在Dialplan中用Lua App运行的不同，前者不会自动获得一个session对象（Table）。当然，独立运行的脚本也可以自行创建session对象。

Event 相关函数

FreeSWITCH使用事件机制进行异步通信。在Lua脚本中，可以"生产"事件，也可以"消费"事件，

FreeSWITCH的事件也跟一个SIP消息类似，它包含一些事件头（Header）和可选的事件正文（Body）。在FreeSWITCH内部使用C语言结构体表示，可以序列化成类似SIP消息的简单文本格式（Plain）、JSON或XML。

下面我们来看一下与事件相关的函数。

freeswitch.Event。初始化一个事件，该事件类型需要在switch_event_types_t枚举类型中有定义，它是在switch_types.h中定义的。如果使用了未定义过的名字，则统一为MESSAGE。下面的例子初始化一个主事件：event = freeswitch.Event("MESSAGE_WAITING") 也可以初始化一个CUSTOM事件，其中第二个参数可以是任意字符串，它将作为事件中的EventSubclass，如：event = freeswitch.Event("CUSTOM", "freeswitch:book")
event:addHeader。给事件增加一个事件头，如： event:addHeader("MWI-Messages-Waiting", "no")

event:addHeader("MWI-Message-Account", "sip:[email protected]")

event:addHeader("Sofia-Profile", "internal")
event:fire。产生（生产）事件，如：event:fire()
event:addBody。给事件增加一个可选的正文，并使用Content-Type头标志正文的类型，如：

event:addHeader("Content-Type", "text/plain")

event:addBody("Hello FreeSWITCH")
event:delHeader。从事件中删除一个头域，下面的例子可以替换from头：

event:delHeader("from")

event:addHeader("from", "[email protected]")
event:getHeader。在收到一个事件后，可以取得其头域的值，如：

event:getHeader("from")

event:getHeader("Caller-Caller-ID-Name")
event:getBody。取得Body的值（如果有的话），如：event:getBody()
event:getType。取得事件的类型（名字），以下两种方法是等价的：

event:getType()

event:getHeader("Event-Name")
event:serialize。将事件序列化成可读的形式（字符串），支持plain text、JSON、XML三种类型，如：

event:serialize()

event:serialize("json")

event:serialize("xml")

完整示例

Lua 复制代码

function log(k, v)
    if not v then v = "[NIL]" end
    freeswitch.consoleLog("INFO", k .. ": " .. v .. "\n")
end
event = freeswitch.Event("CUSTOM", "freeswitch:book")
event:addHeader("Author", "Seven Du")
event:addHeader("Content-Type", "text/plain")
event:addBody("FreeSWITCH: The Definitive Guide")
type = event:getType()
author = event:getHeader("Author")
text=event:serialize()
json=event:serialize("json")
xml=event:serialize("XML")
log("type", type)
log("author", author)
log("text", text)
log("json", json)
log("xml", xml)
event:fire()
log("MSG", "Event Fired")

将上述内容保存到/tmp/event.lua中，执行结果如下

freeswitch>lua /tmp/event.lua

上一篇：打造纯Lua组件化开发模式：Unity xLua框架详解

下一篇：Javascript[ECMAScript] ES6、ES7、ES8、ES9、ES10、ES11、ES12、ES13、ES14[2023]新特性