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 ");

session:consoleLog("notice", "lua rocks ");

session:consoleLog("err",    "lua rocks ");

session:consoleLog("debug",  "lua rocks ");

session:consoleLog("warning","lua rocks ");

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.." *********** ");

    session1 = freeswitch.Session(ostr);

    local hcause = session1:hangupCause();

    freeswitch.consoleLog("notice", "*********** Leg1: " .. hcause .. " - Try: "..retries.." *********** ");

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(<orig_file>, <file_to_insert>, <insertion_sample_point>)

作用：向另一个文件中插入一个文件。总共需要三个参数，第三个参数为抽样（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 .." ")

做个测试，假设现在我们只需要一个数字，并且这个数字必须是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 .." ")

提醒：如果要在正则表达式中匹配“*”键，需要转义两次（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 .." ");

语法:

session:read has 5 arguments: <min digits> <max digits> <file to play> <inter-digit timeout> <terminators>

示例：

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 .. " ")

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 ', tostring(k), tostring(v)))

        end

        if _type == 'table' then

            for k, v in pairs(_type) do

                print(string.format('_type k-> %s v->%s ', tostring(k), tostring(v)))

            end

        end

        print(string.format(' (%s == dtmf) and (obj.digit [%s]) ', _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 .. " ")

    -- 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 .. " " .. "arg: " .. arg .. " ");

   else

      io.write("type: " .. type .. " ");

   end

   if (type == "dtmf") then

      io.write("digit: [" .. obj['digit'] .. "] duration: [" .. obj['duration'] .. "] ");

   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

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

参数：<lang><say_type><say_method>

示例：

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

session：streamFile

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

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

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

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

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