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命令
- 下一篇： 电脑上的文件如何加密如何加密电脑