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: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中
|
|
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.." *********** 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)
|
|
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 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
作用:播放一個宏(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 .. " -- 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 .. " 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"); |
當對信道使用外部文件流時,返回“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
注:譯者翻譯能力有限,歡迎指明
轉自:http://blog.csdn.net/u010317005/article/details/51889022
總結
以上是生活随笔為你收集整理的FreeSwitch LUA API —— Sessions的全部內容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: shutdown命令
- 下一篇: 电脑上的文件如何加密如何加密电脑