FreeSwitch LUA API —— Sessions
API Session作用：應(yīng)用于已存在的會(huì)話（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
作用：應(yīng)答一個(gè)會(huì)話
|
|
session:answered
作用:檢查某個(gè)會(huì)話是否已被應(yīng)答（如果一個(gè)呼叫被應(yīng)答，那么該會(huì)話將被標(biāo)記為true）
session:bridged
作用：檢查當(dāng)前會(huì)話的信道是否已橋接到另外一個(gè)信道上
|
if (session:bridged() == true) do -- Do something end |
session:check_hangup_hook
session:collectDigits
session:consoleLog
作用：從會(huì)話中向FreeSWITCH記錄器記錄一些數(shù)據(jù)。對(duì)應(yīng)的參數(shù)為log級(jí)別和消息
|
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
作用:銷毀會(huì)話并釋放資源。當(dāng)腳本運(yùn)行結(jié)束后這個(gè)會(huì)話事件會(huì)自動(dòng)幫你完成。但如果腳本存在一個(gè)無限循環(huán)，可以使用該函數(shù)結(jié)束會(huì)話
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)不能執(zhí)行被執(zhí)行于該事件
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)不能執(zhí)行被執(zhí)行于該事件
session：flushDigits
session:flushEvents
session:get_uuid
獲得當(dāng)前Session的UUID
session:getDigits
獲得數(shù)字:
l getDigits有三個(gè)參數(shù)：max_digits,terminators,timeout
l max_digits:記錄最大的DTMF數(shù)字鍵音
l terminators:終結(jié)符，用來終結(jié)數(shù)字的輸入
l timeout:允許數(shù)字輸入時(shí)的最大等待毫秒數(shù)
l return:包含已收集的輸入數(shù)字緩沖
l 當(dāng)未觸發(fā)退出條件時(shí)，該方法將會(huì)被一直阻塞
|
Callbacks(DTMF和friends)不能執(zhí)行被執(zhí)行于該事件 |
session:getState
作用：獲得呼叫狀態(tài)，例如CS_EXECUTE。這些呼叫狀態(tài)定義在Switch_types中
|
|
CS_表示Channel Status，以下為完整的信道狀態(tài)表
|
狀態(tài)名 |
含義 |
|
CS_NEW |
信道為新建立的 |
|
CS_INIT |
信道已經(jīng)初始化 |
|
CS_ROUTING |
信道正在查找路由（extension）中 |
|
CS_SOFT_EXECUTE |
信道已準(zhǔn)備好被第三方執(zhí)行 |
|
CS_EXECUTE |
信道正在執(zhí)行它的撥號(hào)計(jì)劃(dialplan) |
|
CS_EXCHANGE_MEDIA |
正在與其他信道交換媒體信息 |
|
CS_PARK |
信道正在等待接受媒體等待命令 |
|
CS_CONSUME_MEDIA |
信道正在處理所有媒體，并舍棄之 |
|
CS_HIBERNATE |
信道正處于休眠狀態(tài) |
|
CS_RESET |
重置狀態(tài) |
|
CS_HANGUP |
掛起狀態(tài)，并且處于中斷的就緒狀態(tài) |
|
CS_REPORTING |
信道已準(zhǔn)備好收集呼叫詳情 |
|
CS_DESTROY |
信道準(zhǔn)備銷毀，并且脫離狀態(tài)機(jī) |
session：getVariable
作用：獲得系統(tǒng)變量，例如${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
作用：掛斷電話并且提供一個(gè)掛斷原因代碼
|
或者
|
|
session：hangupCause
作用：查找掛斷原因或者呼叫（originate）無法發(fā)起的原因
|
-- 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寫的基于掛斷的呼叫重播代碼。它的重播次數(shù)為max_retries1次，并且有兩個(gè)不同的網(wǎng)關(guān)
|
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為兩個(gè)不同的撥號(hào)串
session:hangupStatus
session:insertFile
使用方法:
session:insertFile(<orig_file>, <file_to_insert>, <insertion_sample_point>) |
作用：向另一個(gè)文件中插入一個(gè)文件。總共需要三個(gè)參數(shù)，第三個(gè)參數(shù)為抽樣（sample），對(duì)源文件orig_file進(jìn)行抽樣，然后插入到文件file_to_insert中。結(jié)果文件將以會(huì)話的抽樣率寫入，并且替代orig_file。
因?yàn)槌闃勇蕿榻o定的，因此需要知道文件的抽樣率或者手工計(jì)算抽樣率。例如，被插入的文件a.wav的采樣率為8000HZ，新的采樣時(shí)間為2秒，因此新的insertion_sample_point參數(shù)需設(shè)置為16000。
注意，該方法需要一個(gè)有效的會(huì)話對(duì)象中的激活的信道，因?yàn)樗枰罆?huì)話的采樣率和編碼格式（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數(shù)字。數(shù)字匹配于一個(gè)正則表達(dá)式。無法匹配或者超時(shí)將觸發(fā)播放一個(gè)包含錯(cuò)誤信息的音樂。可選參數(shù)允許在錯(cuò)誤情況下定義extension，并且將輸入的數(shù)字記錄的一個(gè)信道變量中。
語法：
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) |
參數(shù)：
|
min_digits |
允許最小的輸入數(shù)字 |
|
max_digits |
允許最大的輸入數(shù)字 |
|
max_attempts |
當(dāng)無輸入時(shí)重播等待音樂等待數(shù)字的最大次數(shù) |
|
prompt_audio_file |
當(dāng)輸入超時(shí)的提示音樂 |
|
input_error_audio_file |
輸入錯(cuò)誤的提示音樂 |
|
digit_regex |
數(shù)字匹配的正則表達(dá)式 |
|
variable_name |
（可選）該信道變量用于存儲(chǔ)接收的輸入數(shù)字 |
|
digit_timeout |
(可選)輸入數(shù)字間的時(shí)間間隔，單位毫秒 |
|
transfer_on_failure |
（可選）失敗時(shí)的操作，執(zhí)行一個(gè)extension，語法為extension-name[dialplan-id[context]] |
一些注意事項(xiàng)：
l 當(dāng)操作超時(shí)并且重試次數(shù)達(dá)到上限時(shí)，該函數(shù)將返回一個(gè)空字符串
l 當(dāng)輸入長度達(dá)到上限時(shí)，即使終結(jié)符還沒輸入，也會(huì)立即返回
l 如果用戶忘記按下終結(jié)符，但是有正確的輸入，該數(shù)字串也將在下一次超時(shí)后返回
l 在輸入數(shù)字被處理前，會(huì)話是必須得建立起來的。如果你未應(yīng)答呼叫，那么等待音樂會(huì)繼續(xù)播放，但是不會(huì)收集任何數(shù)字。
示例：
下面這個(gè)例子可以引發(fā)FreeSWITCH播放prompt.wav并且監(jiān)聽2-5個(gè)長度大小的數(shù)字，并且以“#”鍵結(jié)束。如果用戶無輸入（或者輸入了非數(shù)字鍵例如“*”鍵），將會(huì)播放error.wav，并且該程序會(huì)重復(fù)允許兩次。
|
digits = session:playAndGetDigits(2, 5, 3, 3000, "#", "/prompt.wav", "/error.wav", "\d+") session:consoleLog("info", "Got DTMF digits: ".. digits .." |
做個(gè)測(cè)試，假設(shè)現(xiàn)在我們只需要一個(gè)數(shù)字，并且這個(gè)數(shù)字必須是1,3或者4，如果用戶嘗試三次都是失敗的，則將執(zhí)行一個(gè)叫“default”的XML文件離的撥號(hào)計(jì)劃（dial plan）了。
如果用戶按下一個(gè)錯(cuò)誤的鍵，數(shù)字將被返回至呼叫器中，信道變量“digits_recieved”會(huì)被設(shè)置為相應(yīng)的值。
|
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 .." |
提醒：如果要在正則表達(dá)式中匹配“*”鍵，需要轉(zhuǎn)義兩次（quote it twice）
|
|
session：preAnswer
作用：預(yù)應(yīng)答一個(gè)會(huì)話
|
|
session:read
作用：播放一個(gè)文件并獲得數(shù)字（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：檢查會(huì)話是否處于活動(dòng)狀態(tài)（在呼叫開始和掛斷之間為true，即激活狀態(tài)）
作用2：如果呼叫被轉(zhuǎn)移（transfer），session.ready將返回false。強(qiáng)烈建議在你的腳本中的任一循環(huán)上階段性的檢查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為在錄音結(jié)束前所能容忍的最大靜音秒數(shù)。如果錄音被例如輸入回呼的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 end if _type == 'table' then for k, v in pairs(_type) do print(string.format('_type k-> %s v->%s end end print(string.format(' 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
作用：播放一個(gè)宏（macro）語音語句
語法：
session:sayPhrase(macro_name [,macro_data] [,language]); |
macro_name:（字符串類型）待播放的語音宏的名字
macro_date:(字符串類型)可選項(xiàng)，傳遞語音宏的日期
language：（字符串類型）可選項(xiàng)，語音宏的語言，默認(rèn)為“en”
為了捕獲事件或者DTMF，可結(jié)合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 |
當(dāng)跟setInputCallback一起使用時(shí)，返回值的含義如下：
l true或者“true”：原因?yàn)樘崾纠^續(xù)說
l 其他字符串：提示被打斷
session：sendEvent
session:setAutoHangup
作用：默認(rèn)情況下，LUA腳本執(zhí)行結(jié)束后則掛斷電話。如果在LUA腳本后還需要執(zhí)行撥號(hào)計(jì)劃（dialplan）后續(xù)的動(dòng)作（action）,需要將setAutoHangup的值設(shè)置為false,因?yàn)槠淠J(rèn)的值為true。
|
|
session:setHangupHook
作用:在LUA腳本中，當(dāng)會(huì)話(session)掛斷后，可以通過setHangupHook來調(diào)用定義的函數(shù)。
|
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
作用：根據(jù)輸入觸發(fā)回調(diào)函數(shù)
|
function my_cb(s, type, obj, arg) if (arg) then io.write("type: " .. type .. " else io.write("type: " .. type .. " end if (type == "dtmf") then io.write("digit: [" .. obj['digit'] .. "] 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"); |
當(dāng)對(duì)信道使用外部文件流時(shí)，返回“true”或者“undefined”將被視為true(表示為繼續(xù)文件流的播放),其他任何操作將被視為false(將終止文件流)。
注意：其他的返回值定義在./src/switch_ivr.c的3359行附近。特別注意的是，每個(gè)返回值必須為STRING類型。
|
返回值 |
效果（當(dāng)傳輸音頻流的時(shí)候） |
|
speed |
未知 |
|
volume |
未知 |
|
pause |
暫停，直到獲得下一個(gè)輸入為止。當(dāng)獲得下一個(gè)輸入時(shí)，繼續(xù)播放。 |
|
stop |
未知 |
|
truncate |
未知 |
|
restart |
未知 |
|
seek |
未知 |
|
true |
等待至播放結(jié)束 |
|
false |
立即暫停播放 |
|
None/NULL |
不要返回這個(gè)值，它會(huì)導(dǎo)致錯(cuò)誤發(fā)生，特別是在python中 |
session：setVariable
作用：在會(huì)話中設(shè)置變量
|
|
session：sleep
|
|
這會(huì)導(dǎo)致回呼至DTMF發(fā)生，但是session:execute(“sleep”，”5000”)不會(huì)。
session：speak
|
session:set_tts_params("flite", "kal"); session:speak("Please say the name of the person you're trying to contact"); |
session:say
作用：播放預(yù)先記錄的聲音文件例如數(shù)字、日期、貨幣等。
參數(shù)：<lang><say_type><say_method>
示例：
|
|
session：streamFile
作用：無限往一個(gè)會(huì)話中輸入流文件
|
|
從一個(gè)采樣點(diǎn)開始傳輸該流文件
|
session:streamFile("/tmp/blah.wav", <sample_count>); |
session：transfer
作用：轉(zhuǎn)移當(dāng)前會(huì)話。參數(shù)為extension、撥號(hào)計(jì)劃(dailplan)或者是文本（context）。
|
|
執(zhí)行完LUA腳本后會(huì)立即結(jié)束，如果不希望呼叫斷開連接，請(qǐng)確保將session:setAutoHangup設(shè)置為false。
如果你是執(zhí)行了以下代碼：
|
session:execute("transfer", "3000 XML default") |
那么執(zhí)行完LUA腳本后不會(huì)終止，即使呼叫已失去控制，亦或是橋接（bridge）可能將失敗
session：unsetInputCallback
作用：取消輸入的回調(diào)函數(shù)
session:waitForAnswer
翻譯出處：https://freeswitch.org/confluence/display/FREESWITCH/mod_lua
注：譯者翻譯能力有限，歡迎指明
轉(zhuǎn)自：http://blog.csdn.net/u010317005/article/details/51889022
總結(jié)
以上是生活随笔為你收集整理的FreeSwitch LUA API —— Sessions的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： shutdown命令
- 下一篇： 电脑上的文件如何加密如何加密电脑