标签：
API Session作用：应用于已存在的会话（Sessions）
目录浏览：
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: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中
|
|
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：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(<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 .."\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）
|
|
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: <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 .. "\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: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：sleep
|
|
这会导致回呼至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：streamFile
作用：无限往一个会话中输入流文件
|
|
从一个采样点开始传输该流文件
|
session:streamFile("/tmp/blah.wav", <sample_count>); |
session：transfer
作用：转移当前会话。参数为extension、拨号计划(dailplan)或者是文本（context）。
|
|
执行完LUA脚本后会立即结束，如果不希望呼叫断开连接，请确保将session:setAutoHangup设置为false。
如果你是执行了以下代码：
|
session:execute("transfer", "3000 XML default") |
那么执行完LUA脚本后不会终止，即使呼叫已失去控制，亦或是桥接（bridge）可能将失败
session：unsetInputCallback
作用：取消输入的回调函数
session:waitForAnswer
翻译出处：https://freeswitch.org/confluence/display/FREESWITCH/mod_lua
注：译者翻译能力有限，欢迎指明FreeSwitch LUA API ——API Sessions
标签：
原文地址：http://blog.csdn.net/u010317005/article/details/51889022
