简介下面的是根据最新的版本r14778(九月九号)中mod_commands模块提供的命令,这些命令可以使用方式有很多种,如下: 控制台具体查看下面内容。 译者注:通过FreeSWITCH控制台使用 API/事件 接口通过API或事件接口调用,如:
脚本接口通过脚本进行调用,如下:
拨号方案调用通过拨号方案进行调用,例子如下: 其他例子: 如果API命令含有多个参数,通常都是以空格隔开。 API命令依赖于加载的相关模块,从每个模块注册的API命令中都能发现它们的踪影。 想要查看全部API命令列表的话,在cli中输入help或者show api即可。 注:如果你想从拨号方案中调用API命令的话,需要先确认拨号方案自带的dptools里面没有类似的命令。 核心命令主要在http://fisheye.freeswitch.org/browse/freeswitch.git/src/mod/applications/mod_commands/mod_commands.c中实现。 注:一些状态或列表命令的返回结果默认是以逗号进行分隔的列表。一些模块的返回结果可能也会包含逗号,这样就导致针对结果的自动化处理比较困难。一个解决方法是,是在命令的最后加上“as xml”,这样返回的就是xml格式的结果。 acl使用acl列表判断ip地址是否为合法访问。 Usage: acl 命令别名alias别名:一种针对常用命令的快捷输入方式 用法: alias add <别名> <命令> | del [<别名>|*] 例子: 别名在重启后需要重设,如果需要重启后仍然生效,需要使用stickyadd参数,如下: 注:只在mod_console中起作用,在fs_cli中无效。 bgapi用于在线程中执行api命令 completeComplete. 译者注:该命令从没用过,不知道干啥的,知道的童鞋,可以来更新该文档。 cond运算指定的条件,并返回结果。 条件表达式支持的条件有: == 等于 例子: 如果第一个值大于第二个,则返回true 拨号方案中的例子: 稍复杂的例子: domain_exists检查指定的domain是否存在: evalEval (noop). 计算字符串,扩展通道变量. 例子: expand执行变量扩展API。 例子: 在这个例子中,扩展的变量是${domain}。比如domain的值是192.168.1.1,则扩展后执行的命令为: fsctl发送freeswitch控制消息。 hupall用于挂断呼向指定号码的通话。参数为: 举个例子来说,杀掉正处于活跃状态、目标号码是1000的通话,命令为: sync_clockFreeSWITCH不信任系统时间。当系统第一次启动的时候,从系统时间中获取样本时间,然后以此为基准使用单调时钟(monotonic clock)。你可以使用命令“fsctl sync_clock”将FreeSWITCH与系统时间进行同步。 注:该命令会立即生效,会影响CDR里面的时间统计。如会导致计费超前或延后,或者记录的挂断时间小于拨打时间。举个例子来说,如果FS的时钟比系统时间迟一个月,当进行时间同步后,CDR的呼叫记录里面就会出现有的呼叫持续时间为1个月。 命令fsctl sync_clock_when_idle要安全很多,作用和上面一样,但是要到系统中所有通道都空闲的时候才开始时间同步。这种方法不会对CDR产生影响。 sync_clock_when_idle要到系统没有通话的时候才开始时间同步 sps该设置会改变swithch.conf文件中设置的sessions-per-second(每秒并发通话数)属性限制 last_sps查询显示目前生效的sessions-per-second属性。 pause可以使用参数inbound或outbound来暂停创建呼入或呼出通话,如果没有指定参数的话,则呼入呼出都暂停。resume的用法类似。 min_dtmf_duration例子: 译者注:没看懂,就不翻译出来误导人了! It is worth noting that many devices squelch in-band DTMF when sending RFC 2833. Devices that squelch in-band DTMF have a certain reaction time and clamping time which can sometimes reach as high as 40ms, though most can do it in less than 20ms. As the shortness of your DTMF event duration approaches this clamping threshold, the risk of your DTMF being ignored as a squelched event increases. If your call is always IP-IP the entire route, this is likely not a concern. However, when your call is sent to the PSTN, the RFC 2833 must be encoded in the audio stream. This means that other devices down the line (possibly a PBX or IVR you are calling into) might start considering your DTMF event a squelched tone and ignore it entirely. For this reason, it is recommended that you do not send DTMF events shorter than 80ms. Checking the current value: fsctl min_dtmf_duration 0 The code recognizes a duration of 0 as a status check. Instead of setting the value to 0, it simply returns the current value. ====max_dtmf_duration==== Example: fsctl max_dtmf_duration 80000 This example sets the max_dtmf_duration switch parameter to 10,000ms (10 seconds). The number is in clock ticks (CT) where CT / 8 = ms. The max_dtmf_duration caps the playout of a DTMF event at the specified duration. Events exceeding this duration will be truncated to this duration. You cannot configure a duration on a profile that exceeds this setting. This setting can be lowered, but cannot exceed 192000 (the default). This setting cannot be set lower than min_dtmf_duration. This setting can be changed in switch.conf.xml. Checking the current value: fsctl max_dtmf_duration 0 The code recognizes a duration of 0 as a status check. Instead of setting the value to 0, it simply returns the current value. ====default_dtmf_duration==== Example: fsctl default_dtmf_duration 2000 This example sets the default_dtmf_duration switch parameter to 250ms. The number is in clock ticks (CT) where CT / 8 = ms. The default_dtmf_duration specifies the DTMF duration to use on originated DTMF events or on events that are received without a duration specified. This value can be increased or lowered. This value is lower-bounded by min_dtmf_duration and upper-bounded by max_dtmf_duration. This setting can be changed in switch.conf.xml. Checking the current value: fsctl default_dtmf_duration 0 The code recognizes a duration of 0 as a status check. Instead of setting the value to 0, it simply returns the current value. ====verbose_events==== Enables verbose events. Verbose events have '''every''' channel variable in '''every''' event for a particular channel. Non-verbose events have only the pre-selected channel variables in the event headers. * This setting can also be set in [[switch.conf.xml]]. global_getvar获取全局变量的值。如果没有提供参数,则返回所有全局变量的值。 global_setvar设置全局变量 例子: group_call返回组呼bridge字符串,组呼定义请参考[[XML User Directory Guide#Groups|call group]]。 +F将会以串行呼叫模式返回组成员(以“|”隔开各成员). +A将会以并行呼叫模式返回组成员(以“,”隔开各成员). +E将会议呼叫模式返回组成员(以:_:隔开各成员),关于企业呼叫请参考[[Freeswitch_IVR_Originate#Enterprise_originate|enterprise fashion]]. 请注意:如果你需要设置在外呼通道上面设置用户变量,需要确保你的domain或被拨打组的变量列表里面没有设置dial-string和group-dial-string,用设置用户默认组里面的dial-string和group-dial-string来替代。这样的话,group_call将会返回user/101,user/将会设置你的外呼通道变量。 help显示所有API命令的帮助信息。 host_lookup针对指定域名做主机查询(host lookup)。 hupall断开现存通话。 挂断所有含有变量,并且值为的通话,挂机原因为。 例子: in_group判断用户是否在指定的组中 is_lan_addr判断IP是否为内网地址 load加载外部模块 md5返回指定数据的MD5值。 module_exists检查模块是否存在。 msleep休眠指定毫秒 nat_map 用法: nat_map [status|reinit|republish] | [add|del] <port> [tcp|udp] [sticky] | [mapping] <enable|disable>
Note: sticky参数用于将映射信息固化下来,在下次FreeSWITCH重启后映射仍然生效。 警告: 如果你有多个网卡,并分别配置了使用相同端口的sip profiles。nat_map在映射端口的时候,会被弄昏头的,不需要将端口映射到哪个sip profile上面,千万别干这种挫事! regex执行正则表达式匹配。该参数会根据是否提供参数而实现不同的功能,如下:
默认的正则表达式分界符是|(管道符)。可以更改为~或者/,只要在字符串的前面加上'm:'。 例子: 版本14727中的逻辑是,如果源字符串匹配匹配到结果,那么条件为false,但是这里仍有一个匹配结果,结果是1001。(这里的翻译是照字面翻译,小伙伴们,你们看懂了没?)
reload重新加载模块。 reloadacl重新加载ACL规则。 reloadxml重新加载conf/freeswitch.xml的配置信息到内存中。 show输出多种(模块)状态报告。 XML格式输出: show foo as xml 修改输出分隔符: show foo as delim |
Tips For Showing Calls and Channels理解show calls/channels真义的最好方式是亲自去尝试。最近(2011.9)又在show命令家族中添加了几位:
这三个命令用于取代简单的"show calls"。 小贴士2: 有时,你需要获取某个特定的uuid,可以使用下面的方式。 like将会搜索下面的关键字段:
注: presence_data 必须在bridge或originate期间设置,而不是在通道已经建立完成后才设置。 shutdown停止FreeSWITCH程序。该命令只在cli中起作用,如果想作为api进行调用,需要使用fsctl shutdown。 警告!在cli中运行shutdown会忽略掉参数,并立即退出!
当使用"elegant", "asap"或者"now"参数后,还可以后跟restart命令,如下: status显示当前FreeSWITCH的运行状态 strftime_tz根据不同的时区,显示格式化后的时间。需要查看linux时区标准列表的,请查看/usr/share/zoneinfo/zone.tab。 示例: strftime_tz US/Eastern %Y-%m-%d %T unload卸载外部模块 version显示FreeSWITCH的版本号 xml_locate xml_locate root: 返回FreeSWITCH使用的所有XML 示例: xml_locate directory domain name example.com xml_wrap使用xml来包装API命令 呼叫管理命令break被废弃,请查看uuid_break命令 create_uuid创建一个新的UUID,并以字符串的形式返回。 originate发起一个新的呼叫 参数:
可选参数: 参数需要使用逗号隔开,例子如下:
更多变量,参考下面的地址: 例子: 又或者,你想将远程注册的sip终端连到拨号规则8600上 再或者,你想将远程注册的sip终端连到另一个远程终端 还或者, 你甚至可以在接通后执行javascript脚本test.js 如果运行的javascript脚本需要传递参数,则需要使用单引号括起来。 在发起呼叫前,设置通道变量 在发起呼叫期间,设置通道变量,并传递给另一个FS 注: 你可以设置任何类型的通道变量,即使是自定义变量。如果变量的值含有空格或逗号等符号,使用单引号括起来即可。 如果你想自造一段回铃音给被呼叫方听,try this: 如果你想发起呼叫后,通道进入"Ring-Ready"状态后就立即返回,try this: 更多信息请查阅return ring ready 你可以将保持等待音乐设置为回铃音,if you want: 你可以在后台发起一个呼叫(异步模式),播放一段60秒的提示消息: 你可以指定被呼叫方的UUID,只需要下面几步:
下面例子作用:发起一个到外部sip服务器echo conference的呼叫,然后转接到本地用户分机上 下面例子作用:向'default'以外的context上的分机发起呼叫(FreePBX会用到该特性,如context名字为context_1,context_2等等) 如果你想对多个分机发起呼叫,可以使用下面的命令: 如果需要在收到early media的时候,将外呼的电话转入会议中,可以使用下面的两个命令,作用一样 下面的例子演示如何在A-leg上面使用loopback和inline pause停止指定通道的媒体播放 uuid_answer应答
uuid_audio调整信道上面的音量,或直接通过一个媒体bug进行静音(读/写) level的值范围从-4到4,默认值为0。 uuid_break断开发送至指定信道的媒体流。举例来说,如果此时正在信道上面播放一个音频文件,使用uuid_break命令,就会断开媒体,呼叫会顺着拨号方案、脚本等往下执行。 如果使用all标记的话,所有信道上面正在排队等待播放的音频文件都会被移除,但是如果没有all标记的话,只有当前正在播放的音频文件会被断开。 uuid_bridge桥接两条呼叫的腿。 uuid_bridge至少需要有一条腿是被呼通的。 uuid_broadcast在一个指定UUID的信道上执行任意一个拨号方案程序。如果指定了某录音文件名,则代表将会在该信道上播放该文件。 执行拨号方案程序的语法规则是“app::args”。 在选定的腿上执行应用程序,执行完毕后挂断,并指明挂机原因。 具体应用举例如下: uuid_buglist列出信道上面的媒体bug(media bugs) uuid_chat发送聊天信息 如果和会话(session,由uuid指定)相关的终端有一个receive_event handler,该消息会被发往终端,并以及时消息的形式显示出来。 uuid_debug_media该命令过去为uuid_debug_audio,但是因为加入了一些视频的内容,所以改为现在的名字。 调试媒体流 用法: 使用“read”、“write”或者“both”(同时调试两个方向)作为语音流的方向,以进行调试。 在前面加上“v”,代表视频流的调试。 Read Format"R %s b=%4ld %s:%u %s:%u %s:%u pt=%d ts=%u m=%d\n" where the values are: Write Format"W %s b=%4ld %s:%u %s:%u %s:%u pt=%d ts=%u m=%d\n" where the values are: uuid_deflect通过发送REFER方法,将当前FreeSWITCH上面的某个已经应答的sip呼叫转移走。 在命令执行后,uuid_deflect等待远端的应答,以此判断转移是否成功。远端返回的sip内容(sip fragment)将会作为uuid_deflect命令的返回结果。如果远端报告REFER成功,FreeSWITCH将会向那条信道发送bye信令。 举例如下: 返回内容: uuid_displace将目标信道上面的语音流替换为指定的录音(文件)。 参数: 用法: 举例如下: uuid_display更新话机的显示内容,前提是话机支持该功能。目前有Polycom和Snom等部分Sip话机支持该功能。 该命令会导致重新协商语音编码。SIP->RTP包的大小应该是0.020。如果在SPA系统话机上,设置为0.030的话,会引起DTMF延迟(DTMF lag)。当话机上的按键被按下的时候,我们可以通过fs_cli看到,但是会有4到6秒的延迟。 uuid_dual_transfer将处于通话中的双方分别转移到不同的目的地。 uuid_dump导出指定会话中的所有变量 导出格式: XML uuid_early_ok停止忽略早期媒体(即正常播放early media)。 如果此时ignore_early_media=true,该命令将会停止忽略早期媒体(让参数ignore_early_media设置不起作用),并正常播放。 用法: uuid_early_ok uuid_exists检查给定的uuid是否存在。 用法: uuid_exists uuid_flush_dtmf刷新DTMF数字缓存,将在排队的DTMF全部送出 Usage: uuid_flush_dtmf uuid_fileman管理正在信道中播放的音频流,该音频来自一个语音文件。 用法: uuid_fileman <cmd:val> 命令如下: Samples,从字面上来讲,就是语音文件前进后退的取样数。在8KHZ的文件中,取样数8000代表的是一秒。同样,在16KHZ的文件中,16000代表的也是一秒。 uuid_getvar获取指定的信道变量 用法: uuid_getvar uuid_hold保持通话 用法: uuid_kill重置(杀掉)指定的信道 用法: uuid_kill [cause] uuid_limitApply or change limit(s) on a specified uuid. Usage: uuid_limit [[/interval]] [number [dialplan [context]]] See also [[Limit]] uuid_mediaReinvite FreeSWITCH out of the media path: Usage: uuid_media [off] Reinvite FreeSWITCH back in: Usage: uuid_media uuid_media_renegAPI command to tell a channel to send a re-invite with optional list of new codecs Usage: uuid_media_reneg uuid_parkPark call Usage: uuid_park uuid_preanswerPreanswer a channel. Usage: uuid_preanswer
uuid_preprocessPre-process Channel Usage: uuid_preprocess <> uuid_recv_dtmfSend DTMF digits to set. Usage: uuid_recv_dtmf [@] Use the character w for a .5 second delay and the character W for a 1 second delay. Default tone duration is 2000ms . uuid_send_dtmfSend DTMF digits. Usage: uuid_send_dtmf [@] Use the character w for a .5 second delay and the character W for a 1 second delay. Default tone duration is 2000ms . uuid_send_infoSend info to the endpoint Usage: uuid_send_info uuid_session_heartbeatUsage: uuid_session_heartbeat [sched] [0|] uuid_setvarSet a variable on a channel. If value is omitted, the variable is unset. Usage: uuid_setvar [value] uuid_setvar_multiSet multiple vars on a channel. Usage: uuid_setvar_multi =[;=[;...]] uuid_simplifyThis command directs FreeSWITCH to remove itself from the SIP signaling path if it can safely do so Usage: uuid_simplify uuid_transferTransfers an existing call to a specific extension within a and . Dialplan may be "xml" or "directory". Usage: uuid_transfer [-bleg|-both] [] [] The optional first argument will allow you to transfer both parties (-both) or only the party to whom is talking.(-bleg) NOTE: if the call has been bridged, and you want to transfer either sides of the call, then you will need to use (or the API equivalent). If it's not set, transfer doesn't really work as you'd expect, and leaves calls in limbo. Record/Playback Commandsuuid_recordRecord the audio associated with the given UUID into a file. The start command causes FreeSWITCH to start mixing all call legs together and saves the result as a file in the format that the file's extension dictates. (if available) The stop command will stop the recording and close the file. If media setup hasn't yet happened, the file will contain silent audio until media is available. Audio will be recorded for calls that are parked. The recording will continue through the bridged call. If the call is set to return to park after the bridge, the bug will remain on the call, but no audio is recorded until the call is bridged again. (TODO: What if media doesn't flow through FreeSWITCH? Will it re-INVITE first? Or do we just not get the audio in that case?) Usage: uuid_record [start|stop] [] Where limit is the max number of seconds to record. If the path is not specified on start it will default to the channel variable "sound_prefix" or FreeSWITCH base_dir when the "sound_prefix" is empty. You may also specify "all" for path when stop is used to remove all for this uuid "stop" command must be followed by option. [[Channel_Variables#Call_Recording_Related|See record's related variables]] Limit Commands[[Limit#API|limit_reset]]Reset a limit backend. [[Limit#API|limit_status]]Retrieve status from a limit backend. [[Limit#API|limit_usage]]Retrieve usage for a given resource. [[Limit#API|uuid_limit_release]]Manually decrease a resource usage by one. [[Limit#API|limit_interval_reset]]Reset the interval counter to zero prior to the start of the next interval. Misc. Commandsbg_systemExecute a system command in the background. Usage: bg_system echoEcho input back to the console echo This text will appear This text will appear file_existsTests whether ''filename'' exists. file_exists filename Examples:
Example dialplan usage: '''Note''' this tests whether FreeSWITCH can see the file, but the file may still be unreadable (permissions). find_user_xmlChecks to see if a user exists; Matches user tags found in the directory, similar to [[user_exists]], but returns an XML representation of the user as defined in the directory (like the one shown in [[Mod_commands#user_exists|user_exists]]). Usage: find_user_xml Where key references a key specified in a directory's user tag, user represents the value of the key, and the domain is the domain the user is assigned to. list_usersLists Users configured in Directory Usage: list_users [group ] [domain ] [user ] [context ] Example: freeswitch@localhost> list_users group default userid|context|domain|group|contact|callgroup|effective_caller_id_name|effective_caller_id_number 2000|default|192.168.20.73|default|sofia/internal/sip:2000@192.168.20.219:5060|techsupport|B#-Test 2000|2000 2001|default|192.168.20.73|default|sofia/internal/sip:2001@192.168.20.150:63412;rinstance=8e2c8b86809acf2a|techsupport|Test 2001|2001 2002|default|192.168.20.73|default|error/user_not_registered|techsupport|Test 2002|2002 2003|default|192.168.20.73|default|sofia/internal/sip:2003@192.168.20.149:5060|techsupport|Test 2003|2003 2004|default|192.168.20.73|default|error/user_not_registered|techsupport|Test 2004|2004 +OK Search items can be combined: freeswitch@localhost> list_users group default user 2004 userid|context|domain|group|contact|callgroup|effective_caller_id_name|effective_caller_id_number 2004|default|192.168.20.73|default|error/user_not_registered|techsupport|Test 2004|2004 +OK sched_apiSchedule an API call in the future. Usage: sched_api [+@] time is the UNIX timestamp at which the command should be executed. If it is prefixed by +, specifies the number of seconds to wait before executing the command. If prefixed by @, it will execute the command periodically everyseconds; for the first time it will be executed after seconds. Scheduled task or group of tasks can be revoked with sched_del or unsched_api. You could put "&" symbol at the end of the line to make command to be executed in its own thread. Example: sched_api +1800 none originate sofia/internal/1000%${sip_profile} &echo() sched_api @600 check_sched log Periodic task is running... sched_broadcastPlay a file to a specific call in the future. Usage: sched_broadcast [+] [aleg|bleg|both] Schedule execution of an application on a chosen leg(s) with optional hangup: Usage: sched_broadcast [+] app[![hangup_cause]]::args [aleg|bleg|both] time is the UNIX timestamp at which the command should be executed (or if it is prefixed by +, the number of seconds to wait before executing the command) Example: sched_broadcast +60 336889f2-1868-11de-81a9-3f4acc8e505e commercial.wav both sched_broadcast +60 336889f2-1868-11de-81a9-3f4acc8e505e say::en\snumber\spronounced\s12345 aleg sched_delRemoves a prior scheduled group or task ID Usage: sched_del <group_name|task_id> The one argument can either be a group of prior scheduled tasks or the returned task-id from sched_api. Example: sched_del my_group sched_del 2 sched_hangupSchedule a running call to hangup. Usage: sched_hangup [+] [] Note: sched_hangup +0 is the same as uuid_kill sched_transferSchedule a transfer for a running call. Usage: sched_transfer [+] [] [] stunExecutes a STUN lookup. Usage: stun [:port] Example: stun stun.freeswitch.org systemExecute a system command. Usage: system The command is passed to the system shell, where it may be expanded or interpreted in ways you don't expect. This can lead to security bugs if you're not careful. For example, the following command is dangerous:
If a malicious remote caller somehow sets their caller ID name to "; rm -rf /", you would unintentionally be executing this shell command: log_caller_name; rm -rf / time_testTime test. Usage: time_test [count] Runs a test to see how bad timer jitter is. It runs the test count times (default 10) and tries to sleep for mss microseconds. It returns the actual timer duration along with an average. Sample: time_test 100 5 test 1 sleep 100 99 test 2 sleep 100 97 test 3 sleep 100 96 test 4 sleep 100 97 test 5 sleep 100 102 avg 98 timer_testTimer test. Usage: timer_test <10|20|40|60|120> [<1..200>] [] Runs a test to see how bad timer jitter is. Unlike time_test, this uses the actual freeswitch timer infrastructure to do the timer test and exercises the timers used for call processing. First argument is the timer interval. Second is the count. Third is the timer name ("show timers" will give you a list) Example: timer_test 20 3 Avg: 16.408ms Total Time: 49.269ms 2010-01-29 12:01:15.504280 [CONSOLE] mod_commands.c:310 Timer Test: 1 sleep 20 9254 2010-01-29 12:01:15.524351 [CONSOLE] mod_commands.c:310 Timer Test: 2 sleep 20 20042 2010-01-29 12:01:15.544336 [CONSOLE] mod_commands.c:310 Timer Test: 3 sleep 20 19928 tone_detectStart Tone Detection on a channel. Usage: tone_detect [ ] unsched_apiUnschedule an api command. Usage: unsched_api url_decodeUsage: url_decode Url decode a string. url_encodeUrl encode a string. Usage: url_encode user_dataRetrieves user information (parameters or variables) as defined in the directory. Usage: user_data @ [attr|var|param] Where user is the user's id, domain is the user's domain, var|param specifies whether the info we're requesting is a variable/parameter, and the name is the name (key) of the variable. Example: will return a result of 1234, and will return a result of 1000 from the example user shown in [[Mod_commands#user_exists|user_exists]], and will return the user's actual alphanumeric ID (i.e. "john") when number-alias="1000" was set as an attribute for that user. user_existsChecks to see if a user exists; Matches user tags found in the directory and returns either true/false: Usage: user_exists Where key references a key specified in a directory's user tag, user represents the value of the key, and the domain is the domain the user is assigned to. Example: will return true where there exists in the directory a user with a key called id whose value equals 1000: In the above example, we also could have tested for randomvar: And we would have received the same results, but: or, Would have returned false. |
FreeSWITCH核心命令
最新推荐文章于 2024-08-30 16:21:29 发布