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

你可能感兴趣的:(freeswitch,freeswitch,lua,session)