FreeSwitch LUA API ——API Sessions

API Session作用：应用于已存在的会话（Sessions）

目录浏览：

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: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(<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）


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: <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: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

作用：播放预先记录的声音文件例如数字、日期、货币等。

参数：<lang><say_type><say_method>

示例：


session:say("12345", "en", "number", "pronounced");

session：streamFile

作用：无限往一个会话中输入流文件


session:streamFile("/tmp/blah.wav");

从一个采样点开始传输该流文件


session:streamFile("/tmp/blah.wav", <sample_count>);

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

注：译者翻译能力有限，欢迎指明

时间： 2024-07-30 09:57:28

FreeSwitch LUA API ——API Sessions的相关文章

VC和VS调用Lua设置以及Lua C API使用。

通过c++调用lua 脚本,    环境VC++6.0    lua  sdk 5.1.4 在调用前先认识几个函数.1．调用lua_open()将创建一个指向Lua解释器的指针.2． luaL_openlibs()函数加载Lua库.3．使用luaL_dofile()加载脚本并运行脚本.4． lua_close()来关闭Lua指向解释器的指针. 5．调用lua_getglobal()将add()函数压入栈顶,add()为lua函数.6．第一个参数x,通过调用lua_pushnumber()入栈.7

Lua常用API

转自:http://www.cnblogs.com/ringofthec/archive/2010/10/22/lua.html 1.  建一个新表 void lua_createtable (lua_State *L, int narr, int nrec) 创建一个新的table, 并把它放在栈顶. narr和nrec分别指定该table的array部分和hash部分的预分配元素数量 无返回值 栈高度+1, 栈顶元素是新table #define lua_newtable(L) lua_cr

lua c API

Lua与C是通过栈进行交换数据的,这个栈与我们在数据结构中所说的栈类似,遵循LIFO规则.下面是从官方文档上截取的关于栈操作的 C API,对其进行分类整理了. 1. 压入元素: void lua_pushnil (lua_State *L); void lua_pushboolean(lua_State *L, int bool); void lua_pushnumber(lua_State *L, double n); void lua_pushinteger (lua_State *L, 

Lua C Api lua_gettable 、lua_settable 、lua_next 使用详解

之前一直没理清lua_gettable和lua_settable的使用,今天理清了,顺便就做下笔记了.1.lua_gettable void lua_gettable (lua_State *L, int index); 把t[k] 值压入堆栈,这里的 t 是指有效索引 index 指向的值,而 k 则是栈顶放的值.这个函数会弹出堆栈上的 key,把结果放在栈上相同位置. 下面举个例子: // 将一个key放到栈顶,这个key为1.如果你的key是字符串,那就用lua_pushstring. l

Lua C API 书籍

https://www.oreilly.com/library/view/creating-solid-apis/9781491986301/ https://www.lua.org/notes/ltn005.html http://www.moonsharp.org/objects.html 原文地址:https://www.cnblogs.com/lilei9110/p/10148419.html

Lua的API函数

1. 基础库 我们在整个教程中使用了各种主题下的基本库. 下表提供了相关页面的链接,并列出了本Lua教程各部分所涵盖的功能. 编号 库/方法 作用 1 错误处理 包括错误处理函数,如断言, 错误,如Lua错误处理中所述. 2 内存管理 包括与垃圾收集相关的自动内存管理功能, 如Lua垃圾收集中所述. 3 dofile ([filename]) 它打开文件并以块的形式执行文件的内容. 4 _G 因此是保存全局环境的全局变量(即_G._G = _G). 5 getfenv ([f]) 返回函数使用的

HttpLuaModule——翻译（Nginx API for Lua） （转）

现在我已经将翻译的内容放到:http://wiki.nginx.org/HttpLuaModuleZh Nginx API for Lua Introduction 各种各样的*_by_lua和*_by_lua_file配置文件服务在都在nginx.conf文件内.这些LUA API只能运行在这些配置文件里面. 这个API有两个标准的包NGX和NDK.这个包在ngx_lua内默认的包. 这个软件包可以这样的引入外部的文件 local say = ngx.say module(...) funct

LUA脚本调用C场景，使用C API访问脚本构造的表

LUA调用C lua解析中集成了一些系统服务, 故脚本中可以访问系统资源, 例如, lua脚本可以调用文件系统接口, 可以调用数学库, 但是总存在一些lua脚本中访问不到的系统服务或者扩展功能, 如果这些系统服务或者扩展功能是使用C语言实现, 那么可以, 使用lua库的对C库的封装方法, 将其中功能封装成lua 接口, 这样脚本就调用这些lua接口调用这些功能. ------- 这种情况,是以lua脚本作为宿主程序. C调用LUA 另外一种场景,是C程序作为宿主程序, 调用LUA脚本, 例如将l

kong个人分享(api网关)

# kong简介 ## 背景 我们在提供api或微服务时,通常借助openresty nginx进行流量转发或者添加一些规则或功能,但是随着服务数量和引用增多,复杂的网络环境, 使维护变得困难,不容易扩展,一些功能也会在多个服务中重复,我们期望有一个工具来集中管理. ![](images/kong_arch.png) ## 简介 Kong 是在客户端和(微)服务间转发API通信的API网关和API服务管理层,通过插件扩展功能.我们可以可以通过增加更多 Kong Server 机器对 Kong 服