From 56c8d1be7e4190f2ad9f031681d99a9847cb8daf Mon Sep 17 00:00:00 2001 From: livem Chan Date: Thu, 27 Mar 2025 17:46:22 +0800 Subject: [PATCH] Update index.mdx Lua code block --- .../Lua-API-Reference/index.mdx | 150 +++++++++--------- 1 file changed, 75 insertions(+), 75 deletions(-) diff --git a/docs/FreeSWITCH-Explained/Client-and-Developer-Interfaces/Lua-API-Reference/index.mdx b/docs/FreeSWITCH-Explained/Client-and-Developer-Interfaces/Lua-API-Reference/index.mdx index 1a5fe54d..5a4e07a3 100644 --- a/docs/FreeSWITCH-Explained/Client-and-Developer-Interfaces/Lua-API-Reference/index.mdx +++ b/docs/FreeSWITCH-Explained/Client-and-Developer-Interfaces/Lua-API-Reference/index.mdx @@ -17,9 +17,9 @@ These methods apply to generating events. ### event:addBody -event:addBody helps in creating custom event. +`event:addBody` helps in creating custom event. -```xml +```lua --Create Custom event custom_msg = "dial_record_id: " .. dial_record_id .. "\n" .. "call_disposition: " .. Disposition .. "\n" .. @@ -73,7 +73,7 @@ Click here to expand the result ### event:fire -```xml +```lua local event = freeswitch.Event("message_waiting"); event:addHeader("MWI-Messages-Waiting", "no"); event:addHeader("MWI-Message-Account", "sip:1000@10.0.1.100"); @@ -87,13 +87,13 @@ event:fire(); This is a generic API call. -```xml +```lua event:getHeader("Caller-Caller-ID-Name") ``` Or, This can be used inside of a dialplan.lua to get certain information -```xml +```lua params:getHeader("variable_sip_req_uri") ``` @@ -105,7 +105,7 @@ Returns the type of this event, either CUSTOM for custom events or one of the [b Use this to dump all available Headers to the console. -```xml +```lua -- Print as text io.write(params:serialize()); io.write(params:serialize("text")); @@ -116,7 +116,7 @@ io.write(params:serialize("json")); Or this to display them as an info message. -```xml +```lua freeswitch.consoleLog("info",params:serialize()) ``` @@ -128,7 +128,7 @@ Sets the priority for the event, but requires a value of type [switch\_priority\ Using luarun to execute this code you can toggle the MWI on a registered phone on and off. -```xml +```lua local event = freeswitch.Event("message_waiting"); event:addHeader("MWI-Messages-Waiting", "no"); event:addHeader("MWI-Message-Account", "sip:1002@10.0.1.100"); @@ -143,7 +143,7 @@ The following methods can be applied to existing sessions. Answer the session: -```xml +```lua session:answer(); ``` @@ -151,7 +151,7 @@ session:answer(); Checks whether the session is flagged as answered (true anytime after the call has been answered) -```xml +```lua session:answered(); ``` @@ -160,7 +160,7 @@ session:answered(); Check to see if this session's channel is bridged to another channel. -```xml +```lua if (session:bridged() == true) do -- Do something end @@ -174,7 +174,7 @@ end Log something to the FreeSWITCH logger from session. Arguments are log level and message. -```xml +```lua session:consoleLog("info", "lua rocks\n"); session:consoleLog("notice", "lua rocks\n"); session:consoleLog("err", "lua rocks\n"); @@ -188,9 +188,9 @@ Destroys the session and releases resources. This is done for you when your scri ### session:execute -session:execute(app, data) +`session:execute(app, data)` -```xml +```lua local mySound = "/usr/local/freeswitch/sounds/music/16000/partita-no-3-in-e-major-bwv-1006-1-preludio.wav" session:execute("playback", mySound) ``` @@ -209,7 +209,7 @@ session:execute("playback", mySound) ### session:get_uuid -```xml +```lua session:get_uuid() ``` @@ -225,7 +225,7 @@ Get digits: * return: buffer containing collected digits * The method blocks until one of the exit criteria is met. -```xml +```lua digits = session:getDigits(5, "#", 3000); session:consoleLog("info", "Got dtmf: ".. digits .."\n"); ``` @@ -234,7 +234,7 @@ session:consoleLog("info", "Got dtmf: ".. digits .."\n"); Get the call state, i.e. "CS\_EXECUTE". The call states are described in "switch\_types.h". -```xml +```lua state=session:getState(); ``` @@ -242,7 +242,7 @@ state=session:getState(); To get system variables such as `${hold\_music}` -```xml +```lua local moh = session:getVariable("hold_music") --[[ events obtained from "switch_channel.c" regards Monroy from Mexico @@ -265,13 +265,13 @@ local moh = session:getVariable("hold_music") You can hang up a session and provide an optional [Hangup Cause Code Table](../../Troubleshooting-Debugging/Hangup-Cause-Code-Table_3964945.mdx#about). -```xml +```lua session:hangup("USER_BUSY"); ``` or -```xml +```lua session:hangup(); -- default normal_clearing ``` @@ -279,7 +279,7 @@ session:hangup(); -- default normal_clearing You can find the hangup cause of an answered call and/or the reason an originated call did not complete. See [Hangup Cause Code Table](../../Troubleshooting-Debugging/Hangup-Cause-Code-Table_3964945.mdx#about). -```xml +```lua -- Initiate an outbound call obSession = freeswitch.Session("sofia/192.168.0.4/1002") @@ -305,7 +305,7 @@ end Here's a Lua example in code which retries a call depending on the hangup cause. It retries max\_retries1 times and alternates between 2 different gateways: -```xml +```lua session1 = null; max_retries1 = 3; retries = 0; @@ -327,7 +327,7 @@ until not ((hcause == 'NO_ROUTE_DESTINATION' or hcause == 'RECOVERY_ON_TIMER_EXP ### session:insertFile -session:insertFile(\, \, \) +`session:insertFile(\, \, \)` Inserts one file into another. All three arguments are required. The third argument is in samples, and is the number of samples into orig\_file that you want to insert file\_to\_insert. The resulting file will be written at the sample rate of the session, and will replace orig\_file. @@ -337,7 +337,7 @@ Note that this method requires an active channel with a valid session object, as **Examples** -```xml +```lua -- On a ulaw channel, insert bar.wav one second into foo.wav: session:insertFile("foo.wav", "bar.wav", 8000) @@ -352,15 +352,15 @@ session:insertFile("bar.wav", "foo.wav", 0) ### session:originate -session:originate is deprecated, use the following construct instead: +`session:originate` is deprecated, use the following construct instead: -```xml +```lua new_session = freeswitch.Session("sofia/gateway/gatewayname/18001234567", session); ``` _The code below is here for the sake of history only; please do not use it going forward._ -```xml +```lua -- this usage of originate is deprecated, use freeswitch.Session(dest, session) new_session = freeswitch.Session(); new_session.originate(session, dest[, timeout]); @@ -378,7 +378,7 @@ Plays a file and collects DTMF digits. Digits are matched against a regular expr ##### Syntax -```xml +```lua digits = session:playAndGetDigits ( min_digits, max_digits, max_attempts, timeout, terminators, prompt_audio_files, input_error_audio_files, @@ -414,7 +414,7 @@ digits = session:playAndGetDigits ( This example causes FreeSWITCH to play _prompt.wav_ and listen for between 2 and 5 digits, ending with the # key. If the user enters nothing (or something other than a digit, like the \* key) _error.wav_ is played, and the process is repeated another two times. -```xml +```lua digits = session:playAndGetDigits(2, 5, 3, 3000, "#", "/prompt.wav", "/error.wav", "\\d+") session:consoleLog("info", "Got DTMF digits: ".. digits .."\n") ``` @@ -423,14 +423,14 @@ This time, we require only one digit, and it must be 1, 3 or 4\. If the user doe If the user presses a correct key, that digit is returned to the caller, and the "digits\_received" channel variable is set to the same value. -```xml +```lua 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") ``` **Reminder:** If you need to match the \* key in the regular expression, you will have to quote it twice: -```xml +```lua digits = session:playAndGetDigits(2, 5, 3, 3000, "#", "/sr8k.wav", "", "\\d+|\\*"); ``` @@ -438,7 +438,7 @@ digits = session:playAndGetDigits(2, 5, 3, 3000, "#", "/sr8k.wav", "", "\\d+|\\* Pre answer the session: -```xml +```lua session:preAnswer(); ``` @@ -446,16 +446,16 @@ session:preAnswer(); Play a file and get digits. -```xml +```lua digits = session:read(5, 10, "/sr8k.wav", 3000, "#"); session:consoleLog("info", "Got dtmf: ".. digits .."\n"); ``` -session:read has 5 arguments: \ \ \ \ \ +`session:read` has 5 arguments: \ \ \ \ \ This shows how you can figure out which terminator was pressed, if any: -```xml +```lua session:setVariable("read_terminator_used", "") digits = session:read(5, 10, "/sr8k.wav", 3000, "*#") terminator = session:getVariable("read_terminator_used") @@ -469,7 +469,7 @@ session:consoleLog("info", "Got dtmf: " .. digits .. " terminator: " .. terminat See #session:hangupCause for more detail on if NOT ready. -```xml +```lua while (session:ready() == true) do -- do something here end @@ -482,7 +482,7 @@ syntax is ended\_by\_silence = session:recordFile(file\_name, max\_len\_secs, si silence\_secs is the amount of silence to tolerate before ending the recording. ended\_by\_silence is 0 if recording was ended by something else, eg an input callback getting dtmfs -```xml +```lua function onInputCBF(s, _type, obj, arg) local k, v = nil, nil local _debug = true @@ -534,7 +534,7 @@ To capture events or DTMF, use it in combination with session:setInputCallback Example: -```xml +```lua function key_press(session, input_type, data, args) if input_type == "dtmf" then session:consoleLog("info", "Key pressed: " .. data["digit"]) @@ -560,15 +560,15 @@ When used with setInputCallback, the return values and meanings are as follows: By default, lua script hangs up when it is done executing. If you need to run the next action in your dialplan after the lua script, you will need to setAutoHangup to false. The default value is true. -```xml +```lua session:setAutoHangup(false) ``` ### session:setHangupHook {#sethanguphook} -In your lua code, you can use setHangupHook to define the function to call when the session hangs up. +In your lua code, you can use `session:setHangupHook` to define the function to call when the session hangs up. -```xml +```lua function myHangupHook(s, status, arg) freeswitch.consoleLog("NOTICE", "myHangupHook: " .. status .. "\n") -- close db_conn and terminate @@ -590,7 +590,7 @@ s:destroy("error message"); ### session:setInputCallback -```xml +```lua function my_cb(s, type, obj, arg) if (arg) then io.write("type: " .. type .. "\n" .. "arg: " .. arg .. "\n"); @@ -638,13 +638,13 @@ Return value effect. Set a variable on a session: -```xml +```lua session:setVariable("varname", "varval"); ``` ### session:sleep -```xml +```lua session:sleep(3000); ``` @@ -652,7 +652,7 @@ session:sleep(3000); ### session:speak -```xml +```lua session:set_tts_params("flite", "kal"); session:speak("Please say the name of the person you're trying to contact"); ``` @@ -665,7 +665,7 @@ Arguments: \\\ Example: -```xml +```lua session:say("12345", "en", "number", "pronounced"); ``` @@ -673,13 +673,13 @@ session:say("12345", "en", "number", "pronounced"); Stream a file endless to the session -```xml +```lua session:streamFile("/tmp/blah.wav"); ``` Stream a file endless to the session starting at sample\_count? -```xml +```lua session:streamFile("/tmp/blah.wav", ); ``` @@ -687,7 +687,7 @@ session:streamFile("/tmp/blah.wav", ); Transfer the current session. The arguments are extensions, dialplan and context. -```xml +```lua session:transfer("3000", "XML", "default"); ``` @@ -702,7 +702,7 @@ If instead you do session:execute("transfer", "3000 XML default") then the execu ## freeswitch.IVRMenu -```xml +```lua local menu = freeswitch.IVRMenu( main, -- ?IVRMenu: the top level menu or nil if this is the top level one name, -- ?string: the name of the menu @@ -729,7 +729,7 @@ Instantiates a new [IVRMenu object](http://docs.freeswitch.org/group%5F%5Fswitch #### menu:bindAction -```xml +```lua menu:bindAction(action, -- string(menu-exit|menu-sub|menu-exec-app|menu-say-phrase|menu-play-sound|menu-back|menu-top) arg, -- ?string: the arg to execute or nil if action is one of string(menu-top|menu-back|menu-exit) bind) -- string: the pattern to bind to @@ -739,7 +739,7 @@ Binds an action to the menu. See the documentation for [IVR Menu](../../Modules/ **Example** -```xml +```lua menu:bindAction("menu-exit", nil, "*") menu:bindAction("menu-back", nil, "5") menu:bindAction("menu-exec-app", "transfer 888 XML default", "7") @@ -747,7 +747,7 @@ menu:bindAction("menu-exec-app", "transfer 888 XML default", "7") #### menu:execute -```xml +```lua menu:execute(session, -- Session: the session on which to execute this menu name) -- ?string: the name of the menu ``` @@ -756,7 +756,7 @@ Executes the instantiated menu on the given session. **Example** -```xml +```lua menu:execute(session, "lua_demo_ivr") ``` @@ -767,7 +767,7 @@ These methods are generic in that they do not apply to a session or an event. Fo Click here to expand... -```xml +```lua -------------------------------------------------------- -- SETUP "ESL.so" FOR LUA TO COMMUNICATE TO FREESWITCH -- apt-get install lua5.2 @@ -802,7 +802,7 @@ print("Your FS version is: " .. version_response_body) ### freeswitch.API -```xml +```lua api = freeswitch.API(); -- get current time in milliseconds time = api:getTime() @@ -810,7 +810,7 @@ time = api:getTime() When calling a Lua script from the dialplan you always have the session object. However, Lua can also be called from the CLI. In either case, it is possible to execute [API](https://wiki.freeswitch.org/wiki/Mod%5Fcommands "Mod commands") commands from within Lua by creating an API object: -```xml +```lua api = freeswitch.API(); reply = api:executeString("version"); ``` @@ -819,7 +819,7 @@ In the above snippet, the Lua variable _reply_ would receive the version number You can do more intricate things as well, like this: -```xml +```lua api = freeswitch.API(); sofia = api:executeString("sofia status"); ``` @@ -828,7 +828,7 @@ The Lua variable _sofia_ would contain the total output of the **sofia status** ### freeswitch.bridge -```xml +```lua session1 = freeswitch.Session("sofia/internal/1001%192.168.1.1"); session2 = freeswitch.Session("sofia/internal/1002%192.168.1.1"); freeswitch.bridge(session1, session2); @@ -836,7 +836,7 @@ freeswitch.bridge(session1, session2); ### freeswitch.consoleCleanLog -```xml +```lua freeswitch.consoleCleanLog("This Rocks!!!\n"); ``` @@ -844,7 +844,7 @@ freeswitch.consoleCleanLog("This Rocks!!!\n"); Log something to the freeswitch logger. Arguments are loglevel, message. -```xml +```lua freeswitch.consoleLog("info", "lua rocks\n"); freeswitch.consoleLog("notice", "lua rocks\n"); freeswitch.consoleLog("err", "lua rocks\n"); @@ -860,7 +860,7 @@ Advantage of this method is that it makes use of connection pooling provided by It works as follows: -```xml +```lua local dbh = freeswitch.Dbh("dsn","user","pass") -- when using ODBC (deprecated) -- OR -- local dbh = freeswitch.Dbh("core:my_db") -- when using sqlite (deprecated, if you have to use this to make it work you should upgrade your FS installation) @@ -921,7 +921,7 @@ freeswitch.email(to, from, headers, body, file, convert_cmd, convert_ext) Example: -```xml +```lua freeswitch.email("receiver@bar.com", "sender@foo.com", "subject: Voicemail from 1234\n", @@ -939,7 +939,7 @@ mp3enc message.wav message.mp3 This is firing a custom event my::event. -```xml +```lua local event = freeswitch.Event("custom", "my::event"); event:addHeader("My-Header", "test"); event:fire(); @@ -962,7 +962,7 @@ Consumes events from FreeSWITCH. **Usage (single event subscription):** -```xml +```lua con = freeswitch.EventConsumer(""[,""]); -- pop() returns an event or nil if no events @@ -977,7 +977,7 @@ con:pop(1,500) **Usage (multiple specific event subscriptions):** -```xml +```lua con = freeswitch.EventConsumer(); con:bind("RELOADXML"); con:bind("SHUTDOWN"); @@ -995,7 +995,7 @@ con:pop(1,500) **Examples:** -```xml +```lua con = freeswitch.EventConsumer("all"); session = freeswitch.Session("sofia/default/dest@host.com"); while session:ready() do @@ -1036,7 +1036,7 @@ end Retrieves a global variable -```xml +```lua my_globalvar = freeswitch.getGlobalVariable("varname") ``` @@ -1046,7 +1046,7 @@ freeswitch.msleep Tells script to sleep for a specified number of milliseconds. **NOTE:** Do **not** use this on a session-based script or bad things will happen. -```xml +```lua -- Sleep for 500 milliseconds freeswitch.msleep(500); ``` @@ -1055,14 +1055,14 @@ freeswitch.msleep(500); Create a new session. -```xml +```lua local session = freeswitch.Session("sofia/10.0.1.100/1001"); session:transfer("3000", "XML", "default"); ``` Create a new session with execute\_on\_answer variable set. -```xml +```lua local session = freeswitch.Session("[execute_on_answer=info notice]sofia/10.0.1.100/1001"); ``` @@ -1072,7 +1072,7 @@ local session = freeswitch.Session("[execute_on_answer=info notice]sofia/10.0.1. You can write FreeSWITCH API commands \*in Lua\* by using the lua FreeSWITCH API command to run a script and pass the arguments in, then whatever you write with the stream object is what you get as a reply to that command. For example, given a script in the scripts directory called hello.lua with the following content: -```xml +```lua stream:write("hello world") ``` @@ -1089,7 +1089,7 @@ Would set the channel variable "foo" to "hello world". #### Web page interaction (via mod_xml_rpc) -```xml +```lua -- -- lua/api.lua -- @@ -1119,7 +1119,7 @@ stream:write(env:serialize() .. "\n\n"); #### Example: Call Control -```xml +```lua -- -- call control lua script -- @@ -1178,7 +1178,7 @@ Add an extension to test this feature: Then add freeswitch/scripts/hook-test.lua: -```xml +```lua -- hook-test.lua -- demonstrates using env to look at channel variables in hangup hook script