FreeSwitch LUA API —— Sessions

API Session作用：应用于已存在的会话（Sessions）

目录浏览：

• API Sessions
  • session:answer
  • session:answered
  • session:bridged
  • session:check_hangup_hook
  • session:collectDigits
  • session:consoleLog
  • session:destroy
  • session:execute
  • session:executeString
  • session:flushDigits
  • session:flushEvents
  • session:get_uuid
  • session:getDigits
  • session:getState
  • session:getVariable
  • session:hangup
  • session:hangupCause
  • session:hangupState
  • session:insertFile
  • session:mediaReady
  • session:originate
  • session:playAndGetDigits
    • Syntax
    • Arguments
    • Discussion
    • Examples
  • session:preAnswer
  • session:read
  • session:ready
  • session:recordFile
  • session:sayPhrase
  • session:sendEvent
  • session:setAutoHangup
  • session:setHangupHook
  • session:setInputCallback
  • session:setVariable
  • session:sleep
  • session:speak
  • session:say
  • session:streamFile
  • session:transfer
  • session:unsetInputCallback
  • session:waitForAnswer

session：answer

作用：应答一个会话

session:answer();

 

session:answered

作用:检查某个会话是否已被应答（如果一个呼叫被应答，那么该会话将被标记为true）

 

session:bridged

作用：检查当前会话的信道是否已桥接到另外一个信道上

if (session:bridged() == true) do     -- Do something end

 

session:check_hangup_hook

 

session:collectDigits

 

session:consoleLog

作用：从会话中向FreeSWITCH记录器记录一些数据。对应的参数为log级别和消息

session:consoleLog("info",   "lua rocks\n"); session:consoleLog("notice", "lua rocks\n"); session:consoleLog("err",    "lua rocks\n"); session:consoleLog("debug",  "lua rocks\n"); session:consoleLog("warning","lua rocks\n");

 

session:destroy

作用:销毁会话并释放资源。当脚本运行结束后这个会话事件会自动帮你完成。但如果脚本存在一个无限循环，可以使用该函数结束会话

 

session:execute

使用方法:session:execute(app,data)

local mySound = "/usr/local/freeswitch/sounds/music/16000/partita-no-3-in-e-major-bwv-1006-1-preludio.wav" session:execute("playback", mySound)

注意：Callbacks(DTMF和friends)不能执行被执行于该事件

 

session:executeString

使用方法：session:execute(api_string)

local mySound = "/usr/local/freeswitch/sounds/music/16000/partita-no-3-in-e-major-bwv-1006-1-preludio.wav" session:executeString("playback "..mySound)

注意: Callbacks(DTMF和friends)不能执行被执行于该事件

 

session：flushDigits

 

session:flushEvents

 

session:get_uuid

获得当前Session的UUID

 

session:getDigits

获得数字:

l  getDigits有三个参数：max_digits,terminators,timeout

l  max_digits:记录最大的DTMF数字键音

l  terminators:终结符，用来终结数字的输入

l  timeout:允许数字输入时的最大等待毫秒数

l  return:包含已收集的输入数字缓冲

l  当未触发退出条件时，该方法将会被一直阻塞

Callbacks(DTMF和friends)不能执行被执行于该事件

 

session:getState

作用：获得呼叫状态，例如CS_EXECUTE。这些呼叫状态定义在Switch_types中

state=session:getState();

 

CS_表示Channel Status，以下为完整的信道状态表

状态名	含义
CS_NEW	信道为新建立的
CS_INIT	信道已经初始化
CS_ROUTING	信道正在查找路由（extension）中
CS_SOFT_EXECUTE	信道已准备好被第三方执行
CS_EXECUTE	信道正在执行它的拨号计划(dialplan)
CS_EXCHANGE_MEDIA	正在与其他信道交换媒体信息
CS_PARK	信道正在等待接受媒体等待命令
CS_CONSUME_MEDIA	信道正在处理所有媒体，并舍弃之
CS_HIBERNATE	信道正处于休眠状态
CS_RESET	重置状态
CS_HANGUP	挂起状态，并且处于中断的就绪状态
CS_REPORTING	信道已准备好收集呼叫详情
CS_DESTROY	信道准备销毁，并且脱离状态机

 

session：getVariable

作用：获得系统变量，例如${hold_music}

local moh = session:getVariable("hold_music") --[[ events obtained from "switch_channel.c"  regards Monroy from Mexico ]]      session:getVariable("context");     session:getVariable("destination_number");     session:getVariable("caller_id_name");     session:getVariable("caller_id_number");     session:getVariable("network_addr");     session:getVariable("ani");     session:getVariable("aniii");     session:getVariable("rdnis");     session:getVariable("source");     session:getVariable("chan_name");     session:getVariable("uuid");

 

session：hangup

作用：挂断电话并且提供一个挂断原因代码

session:hangup("USER_BUSY");

或者

session:hangup(); -- default normal_clearing

 

session：hangupCause

作用：查找挂断原因或者呼叫（originate）无法发起的原因

-- Initiate an outbound call obSession = freeswitch.Session("sofia/192.168.0.4/1002")   -- Check to see if the call was answered if obSession:ready() then     -- Do something good here else    -- This means the call was not answered ... Check for the reason     local obCause = obSession:hangupCause()     freeswitch.consoleLog("info", "obSession:hangupCause() = " .. obCause )     if ( obCause == "USER_BUSY" ) then              -- SIP 486        -- For BUSY you may reschedule the call for later     elseif ( obCause == "NO_ANSWER" ) then        -- Call them back in an hour     elseif ( obCause == "ORIGINATOR_CANCEL" ) then   -- SIP 487        -- May need to check for network congestion or problems     else        -- Log these issues     end end

 

基于挂断缘由的重播示例：

以下代码为用LUA写的基于挂断的呼叫重播代码。它的重播次数为max_retries1次，并且有两个不同的网关

session1 = null; max_retries1 = 3; retries = 0; ostr = ""; repeat      retries = retries + 1;     if (retries % 2) then ostr = originate_str1;     else ostr = originate_str12; end     freeswitch.consoleLog("notice", "*********** Dialing Leg1: " .. ostr .. " - Try: "..retries.." ***********\n");     session1 = freeswitch.Session(ostr);     local hcause = session1:hangupCause();     freeswitch.consoleLog("notice", "*********** Leg1: " .. hcause .. " - Try: "..retries.." ***********\n"); until not ((hcause == 'NO_ROUTE_DESTINATION' or hcause == 'RECOVERY_ON_TIMER_EXPIRE' or hcause == 'INCOMPATIBLE_DESTINATION' or hcause == 'CALL_REJECTED' or hcause == 'NORMAL_TEMPORARY_FAILURE') and (retries < max_retriesl1))

注意：originate_str1和originate_str2为两个不同的拨号串

 

session:hangupStatus

 

session:insertFile

使用方法: 

session:insertFile(, , )

作用：向另一个文件中插入一个文件。总共需要三个参数，第三个参数为抽样（sample），对源文件orig_file进行抽样，然后插入到文件file_to_insert中。结果文件将以会话的抽样率写入，并且替代orig_file。

因为抽样率为给定的，因此需要知道文件的抽样率或者手工计算抽样率。例如，被插入的文件a.wav的采样率为8000HZ，新的采样时间为2秒，因此新的insertion_sample_point参数需设置为16000。

注意，该方法需要一个有效的会话对象中的激活的信道，因为它需要知道会话的采样率和编码格式（codec）

-- On a ulaw channel, insert bar.wav one second into foo.wav: session:insertFile("foo.wav", "bar.wav", 8000)   -- Prepend bar.wav to foo.wav: session:insertFile("foo.wav", "bar.wav", 0)   -- Append bar.wav to foo.wav: session:insertFile("bar.wav", "foo.wav", 0)

 

session：mediaReady

 

session:originate

该方法已被舍弃，可用以下代码替代

new_session= freeswitch.Session(“sofia/gateway/gatewayname/xxxxx”session);

 

session：playAndGetDigits

该方法用于播放文件和收集DTMF数字。数字匹配于一个正则表达式。无法匹配或者超时将触发播放一个包含错误信息的音乐。可选参数允许在错误情况下定义extension，并且将输入的数字记录的一个信道变量中。

语法：

digits = session:playAndGetDigits (           min_digits, max_digits, max_attempts, timeout, terminators,           prompt_audio_files, input_error_audio_files,           digit_regex, variable_name, digit_timeout,           transfer_on_failure)

参数：

min_digits	允许最小的输入数字
max_digits	允许最大的输入数字
max_attempts	当无输入时重播等待音乐等待数字的最大次数
prompt_audio_file	当输入超时的提示音乐
input_error_audio_file	输入错误的提示音乐
digit_regex	数字匹配的正则表达式
variable_name	（可选）该信道变量用于存储接收的输入数字
digit_timeout	(可选)输入数字间的时间间隔，单位毫秒
transfer_on_failure	（可选）失败时的操作，执行一个extension，语法为extension-name [dialplan-id [context]]

一些注意事项：

l  当操作超时并且重试次数达到上限时，该函数将返回一个空字符串

l  当输入长度达到上限时，即使终结符还没输入，也会立即返回

l  如果用户忘记按下终结符，但是有正确的输入，该数字串也将在下一次超时后返回

l  在输入数字被处理前，会话是必须得建立起来的。如果你未应答呼叫，那么等待音乐会继续播放，但是不会收集任何数字。

示例：

下面这个例子可以引发FreeSWITCH播放prompt.wav并且监听2-5个长度大小的数字，并且以“#”键结束。如果用户无输入（或者输入了非数字键例如“*”键），将会播放error.wav，并且该程序会重复允许两次。

digits = session:playAndGetDigits(2, 5, 3, 3000, "#", "/prompt.wav", "/error.wav", "\\d+") session:consoleLog("info", "Got DTMF digits: ".. digits .."\n")

 

做个测试，假设现在我们只需要一个数字，并且这个数字必须是1,3或者4，如果用户尝试三次都是失败的，则将执行一个叫“default”的XML文件离的拨号计划（dial plan）了。

如果用户按下一个错误的键，数字将被返回至呼叫器中，信道变量“digits_recieved”会被设置为相应的值。

digits = session:playAndGetDigits(1, 1, 3, 3000, "", "/menu.wav", "/error.wav", "[134]", "digits_received", 3, "operator XML default") session:consoleLog("info", "Got DTMF digits: ".. digits .."\n")

 

提醒：如果要在正则表达式中匹配“*”键，需要转义两次（quote it twice）

digits = session:playAndGetDigits(2, 5, 3, 3000, "#", "/sr8k.wav", "", "\\d+|\\*");

 

session：preAnswer

作用：预应答一个会话

session:preAnswer();

 

session:read

作用：播放一个文件并获得数字（digits）

digits = session:read(5, 10, "/sr8k.wav", 3000, "#");                                session:consoleLog("info", "Got dtmf: ".. digits .."\n");

语法:

session:read has 5 arguments:

示例：

session:setVariable("read_terminator_used", "") digits = session:read(5, 10, "/sr8k.wav", 3000, "*#") terminator = session:getVariable("read_terminator_used") session:consoleLog("info", "Got dtmf: " .. digits .. " terminator: " .. terminator .. "\n")

 

session：ready

作用1：检查会话是否处于活动状态（在呼叫开始和挂断之间为true，即激活状态）

作用2：如果呼叫被转移（transfer），session.ready将返回false。强烈建议在你的脚本中的任一循环上阶段性的检查session.ready的值，这样一旦返回false可立即退出。

while (session:ready() == true) do                                    -- do something here                                end

 

session：recordFile

语法为：

ended_by_silence = session:recordFile(file_name, max_len_secs, silence_threshold, silence_secs)

silence_secs为在录音结束前所能容忍的最大静音秒数。如果录音被例如输入回呼的DTMF键中断，则ended_by_silence是0。

function onInputCBF(s, _type, obj, arg)     local k, v = nil, nil     local _debug = true     if _debug then         for k, v in pairs(obj) do             printSessionFunctions(obj)             print(string.format('obj k-> %s v->%s\n', tostring(k), tostring(v)))         end         if _type == 'table' then             for k, v in pairs(_type) do                 print(string.format('_type k-> %s v->%s\n', tostring(k), tostring(v)))             end         end         print(string.format('\n(%s == dtmf) and (obj.digit [%s])\n', _type, obj.digit))     end     if (_type == "dtmf") then         return 'break'     else         return ''     end end   recording_dir = '/tmp/' filename = 'myfile.wav' recording_filename = string.format('%s%s', recording_dir, filename)   if session:ready() then     session:setInputCallback('onInputCBF', '');     -- syntax is session:recordFile(file_name, max_len_secs, silence_threshold, silence_secs)     max_len_secs = 30     silence_threshold = 30     silence_secs = 5     test = session:recordFile(recording_filename, max_len_secs, silence_threshold, silence_secs);     session:consoleLog("info", "session:recordFile() = " .. test ) end

 

session:sayPhrase

作用：播放一个宏（macro）语音语句

语法：

session:sayPhrase(macro_name [,macro_data] [,language]);

macro_name:（字符串类型）待播放的语音宏的名字

macro_date:(字符串类型)可选项，传递语音宏的日期

language：（字符串类型）可选项，语音宏的语言，默认为“en”

为了捕获事件或者DTMF，可结合session:setInputCallback使用。

示例：

function key_press(session, input_type, data, args)   if input_type == "dtmf" then     session:consoleLog("info", "Key pressed: " .. data["digit"])     return "break"   end end if session:ready() then   session:answer()   session:execute("sleep", "1000")   session:setInputCallback("key_press", "")   session:sayPhrase("voicemail_menu", "1:2:3:#", "en") end

当跟setInputCallback一起使用时，返回值的含义如下：

l  true或者“true”：原因为提示继续说

l  其他字符串：提示被打断

 

session：sendEvent

 

session:setAutoHangup

作用：默认情况下，LUA脚本执行结束后则挂断电话。如果在LUA脚本后还需要执行拨号计划（dialplan）后续的动作（action）,需要将setAutoHangup的值设置为false,因为其默认的值为true。

session:setAutoHangup(false)

 

session:setHangupHook

作用:在LUA脚本中，当会话(session)挂断后，可以通过setHangupHook来调用定义的函数。

function myHangupHook(s, status, arg)     freeswitch.consoleLog("NOTICE", "myHangupHook: " .. status .. "\n")     -- close db_conn and terminate     db_conn:close()     error() end   blah="w00t"; session:setHangupHook("myHangupHook", "blah")

其他可能退出脚本的语句（或者是抛出异常）

return "exit"; or return "die"; or s:destroy("error message");

 

session：setInputCallBack

作用：根据输入触发回调函数

function my_cb(s, type, obj, arg)    if (arg) then       io.write("type: " .. type .. "\n" .. "arg: " .. arg .. "\n");    else       io.write("type: " .. type .. "\n");    end    if (type == "dtmf") then       io.write("digit: [" .. obj['digit'] .. "]\nduration: [" .. obj['duration'] .. "]\n");    else       io.write(obj:serialize("xml"));       e = freeswitch.Event("message");       e:add_body("you said " .. obj:get_body());       session:sendEvent(e);    end end blah="w00t"; session:answer(); session:setInputCallback("my_cb", "blah"); session:streamFile("/tmp/swimp.raw");

当对信道使用外部文件流时，返回“true”或者“undefined”将被视为true(表示为继续文件流的播放),其他任何操作将被视为false(将终止文件流)。

 

注意：其他的返回值定义在./src/switch_ivr.c的3359行附近。特别注意的是，每个返回值必须为STRING类型。

返回值	效果（当传输音频流的时候）
speed	未知
volume	未知
pause	暂停，直到获得下一个输入为止。当获得下一个输入时，继续播放。
stop	未知
truncate	未知
restart	未知
seek	未知
true	等待至播放结束
false	立即暂停播放
None/NULL	不要返回这个值，它会导致错误发生，特别是在python中

 

session：setVariable

作用：在会话中设置变量

session:setVariable("varname", "varval");

 

session：sleep

session:sleep(3000);

这会导致回呼至DTMF发生，但是session:execute(“sleep”，”5000”)不会。

 

session：speak

session:set_tts_params("flite", "kal"); session:speak("Please say the name of the person you're trying to contact");

 

session:say

作用：播放预先记录的声音文件例如数字、日期、货币等。

参数：

示例：

session:say("12345", "en", "number", "pronounced");

 

session：streamFile

作用：无限往一个会话中输入流文件

session:streamFile("/tmp/blah.wav");

从一个采样点开始传输该流文件

session:streamFile("/tmp/blah.wav", );

 

session：transfer

作用：转移当前会话。参数为extension、拨号计划(dailplan)或者是文本（context）。

session:transfer("3000", "XML", "default");

执行完LUA脚本后会立即结束，如果不希望呼叫断开连接，请确保将session:setAutoHangup设置为false。

 

如果你是执行了以下代码：

session:execute("transfer", "3000 XML default")

那么执行完LUA脚本后不会终止，即使呼叫已失去控制，亦或是桥接（bridge）可能将失败

 

session：unsetInputCallback

作用：取消输入的回调函数

 

session:waitForAnswer

翻译出处：https://freeswitch.org/confluence/display/FREESWITCH/mod_lua

注：译者翻译能力有限，欢迎指明

转自：http://blog.csdn.net/u010317005/article/details/51889022