[freeswitch]mod_dptools功能总结（updating）
mod_dptools功能总结
前言
freeSWITCH的mod_dptools模块各功能总结，这里只是整理下功能，具体用法参考官方wiki
-
answer
“接通”。建立aleg和fs之间的音频流，和bleg没关系。一般来说fs在接受dtmf或者播放语音之前都要先接通。在接通之后仍可以bridge到其它终端（接通后再bridge其实就是转接），回铃音由transfer_ringback设置。 -
att_xfer
转接。本来是A->B，att_xfer会让C加入进来，从而变成A->C。可以直接使用或者和绑定dtmf的功能搭配使用。详细使用方式和例子参考官方文档。 -
bgsystem
后台执行一个系统命令。不会阻塞当前dialplan。bg就是backgroud的意思。 -
bind_digit_action****和bind_meta_app
绑定dtmf。不同之处在于，bind_digit_action比bind_meta_app更灵活，是bind_meta_app的升级版。 -
break
终止application。终止一个当前channel正在运行的application，下一个application继续执行不受影响。也可以用来终止所有application。 -
bridge
桥接。把一个新channel和当前channel连接。经常用来把一通来电转给多个被叫（可以同时或者轮流）。bridge有很多可选功能：设置等待时长、无媒体模式、设置callerID和回铃音、通话驻留(及被叫被占用时主叫等待)。 -
bridge_export
和export的区别在于bridge_export适用于任何类型的bridge。例如使用uuid_transfer时export不生效而bridge_export生效。 -
callcenter
呼叫中心功能。具体的用法和配置可以参考mod_callcenter模块。 -
capture
操作通道变量中的数组。 -
chat
向一个IM客户端发送文本消息。 -
check_acl
检查呼叫来源是否匹配acl，不匹配则终止通话（cause code为normal_clearing）。 -
clear_digit_action
删除所有dtmf功能绑定。 -
clear_speech_cache
Clears out the speech handle cache（ 没用过，不太清楚） -
cng_plc
生成舒适噪音。 -
deflect
转接。只能用于已经建立(或者说已接通)的通话。deflect会挂断当前的通话，并向通话发起者发送一个REFER消息和一个新的INVITE消息。注意和redirect命令的区别，当通话没有建立时，转接不能用deflect，但是可以用redirect。 -
delay_echo
延时“回声”。 -
detect_silence
监听静默音。暂停（阻塞）diaplan的执行，在一段时间内持续检测静默音。当检测到静默音或者检测超时后，dialplan继续执行。静默音由silence_thresh（理解为通道能量阈值）和silence_hits（理解为时长）两个参数决定。 -
detect_speech
语音识别。 -
digit_action_set_realm
和bind_digit_action一起，在绑定dtmf时使用，具体可以参考官网bind_digit_action的部分 -
displace_session
（向一个channel中） 播放一个文件或音频流。 -
eavesdrop
监听。监听指定的uuid通道，如果是持续或者永久的监听，一般使用mod_spy。 -
echo
播放回声。会返回任何东西，除了声音外，也会返回dtmf。可以用这个功能来测试通道的延时。 -
endless_playback
持续播放一个文件。 -
env-set
把一个系统环境变量的值赋给一个自定义变量。 -
eval
执行api，在控制台打印日志。例如在控制台输入eval ${distributor ucrs ${sofia profile external gwlist down}}，eval会调用内部api和相关模块进行解析，最终输出解析结果
-
event
用于发布一个自定义事件。 -
execute_extension
在当前dialplan创建一个一次性的extension并执行，执行完之后返回当前diaplan。要注意的是如果执行的是transfer则不会返回。 -
export
把一个变量从A leg传递到B leg。（使用export后A leg和B leg都会设置此变量，如果只想在B leg上设置变量，需要使用nolocal，具体用法参考官方文档） -
fax detect
传真检测。 -
file_string
用于依次播放/写入某个声音文件（如果某个失败了，则跳过进行下一个）。例如搭配playback或者record_session使用。不同的声音文件之间用感叹号分割。更多用法参考官方文档。 -
flush dtmf
清除一个channel接收到的dtmf。 -
gentones
生成TGML铃音。和tone_stream的功能差不多。但是tone_stream用的更多。 -
group
用于群组呼叫，对群组做添加或删除。 -
hangup
挂断当前通道。可以赋值挂断原因。（当挂断失败时可以检查一下hangup_after_bridge变量，再确认一下是否接到了BYE信令） -
hold
发送hold信息。 -
info
打印通道相关信息。在调试和排障时是非常有用的。 -
inline dialplan
内联拨号计划。和普通的dialplan区别在于，inline dialplan不需要，也不需要 ，只要有action就行了： 'app1:arg1,app2:arg2,app3:arg3' inline，例如下面这句话就完成了先打电话，再设置通道变量，最后播放wav的操作：
originate sofia/gateway/my_gw/user@domain.com 'set:myvar=myvalue,info:,playback:foo.wav' inline
其中，'set:myvar=myvalue,info:,playback:foo.wav'代替了正常diaplan中的xml配置。
-
intercept
将当前通道转给另一通通话的a leg或者b leg（通过uuid）。例如，当通话没有成功bridge或者成功接通时，可以用intercept将当前通话转给其它通道。具体使用方法参考官方文档。 -
IVR menu
IVR菜单。创建IVR菜单（使用XML配置文件：/autoload_configs/ivr.conf.xml）。详细内容这里不写了，参考IVR Menu或者IVR。 -
limit
设置外呼或者来电的最大数量。当到达最大数量时，通话将转向指定路由。通过limit
可以实现很多功能，例如：限制最大并发通话数、对某个fs功能的限流、限制指定时间内最大通话量等等。详细用户和说明参考官方文档。 -
log
在控制台打印日志。这个很常用不多说了。 -
loop_playback
循环播放某个文件（指定次数）。 -
media_reset
重置媒体设置。这个功能针对的是媒体的bypass设置和proxy设置 -
mkdir
创建一个目录（有可能会因为系统权限问题创建失败）。 -
multiset
同时设置多个通道变量。多个变量之间默认以空格分割：
如果想指定分割符，用"^^"指定：
-
mutex
阻塞呼叫流，一次仅允许一个呼叫流。没有用过，但是个人理解是同一时间内只允许一通话务通过这个diaplan。用法见官方文档。 -
page
向多个通道播放一段录好的文件。 -
park
挂起。挂起的时候不会播放任何声音，用户体验比较差，一般可以考虑用hold代替。 -
phrase
播放一段预定义好的文本。通过xml的方式进行配置并生成语音。更详细的资料和使用方式可以参考 Speech Phrase Management 。 -
pickup
pickup通道是一个虚拟的通道，可以利用这个通道实现一些特殊功能。没怎么用过，详细参考官方文档吧。 -
play_and_detect_speech
在做语音识别（ASR）的时候播放音频。音频可以是文件也可以是TTS语音。 -
play_and_get_digits
播放提示音并获取用户输入的dtmf。 -
playback
在当前通道播放音频。非常常用的一个功能。支持多种格式的音频，例如常见的*.wav（需加载mod_sndfile模块）和*.mp3（需加载mod_shout模块）。 -
pre answer
在并未接通的情况下，建立早期媒体连接(early media)。例如彩铃、语音提示等就是early media（对应sip状态码183）。这个在实际中也是很常用的，比如在被叫拒接时，给主叫播放一段语音，而不是直接挂断。 -
presence
发布一个PRESENCE_IN或PRESENCE_OUT事件。这个事件是用于BLF（Busy Lamp Field）的，BLF的作用是标记voip用户是否在线，是否可以进行呼叫。 -
privacy
将主叫设为隐私。具体用法和作用有待研究。 -
queue_dtmf
发送一串dtmf（bridge成功后）。 -
read
获取dtmf。在获取到dtmf之前可以播放一段定制的音频。 -
record和 record_session
录音。二者的区别在于，前者是阻塞的，而后者是非阻塞的；录音后的录音文件可以保存在指定路径下，也可以和http_cache模块搭配，直接将录音文件通过接口进行上传。录音功能还是比较常用的，实际中录音的场景也比较多，这里不展开说了，具体用法和对录音过程的控制参考官方文档。 -
redirect
转接。只能用于通话还未接通的时候，如果通话接通后的转接用deflect功能。 -
regex
正则匹配。严格来说这不是直接用在dialplan里的，而是一个api，想要在dialplan中调用api可以借助set。实际使用参考官方文档。 -
remove_bugs
移除所有的media bugs， 这里的media bug指的是fs的媒体旁路输出机制，record_session、tone_detect等功能都使用了这一机制。media bug -
rename
重命名一个文件。没啥好说的。 -
respond
发送一个sip回应。例如，如果你想给某个终端发送一个未授权的407消息：
-
ring_ready
告知主叫已经振铃，即给主叫发送一个180信令。 -
say
顾名思义，“读”。播放提前录好的音频，或者读出日期、时间、dtmf等。具体用法详见官方文档。 -
sched broadcast
预定一个广播。例如一小时后向主被叫双方播放一段音频： -
sched transfer
预定一个转接。例如10分钟后将通话转入default.xml：
-
sched cancel
根据last_sched_id取消定时任务（由上面的sched broadcast或sched transfer设置的transfer或broadcast）。 -
sched hungup
定时挂断。可以用来限制呼叫时长。 -
send_display
发送一个信息包用于展示，如果终端支持的话会显示这个信息。 -
send dtmf
发送dtmf。例如： -
session loglevel
更改当前通道的loglevel（覆盖switch.conf.xml中的设置）。 -
set
设置通道变量。很常用，没什么好说的。需要注意的是，set不会立即生效，执行完当前的dialplan之后才会生效。如果执行set之后希望立即生效，搭配inline使用。 -
set_global
设置全局变量（全局指的是这个变量对其它的channel也生效）。 -
set_name
重命名一个channel。 -
set_profile_var
给通道事件（channel event）增加一个header。只用于通道事件中。 -
set_user
Pulls all of the channel variables defined for a user as if the user had auth’d. -
set audio level
增大或减小音量级别。其实就是调音量的。调整范围：-4~4。一般调音量是用户终端的事，fs端最好不要调整。 -
set zombie exec
给当前的channel立个flag：zombie flag。这个flag立完之后，即使这个channel挂断，仍然会继续执行channel中的command。 -
sleep
顾名思义，sleep会“暂停”一个通道，这期间对音频的处理并不会暂停，仍会“消费”音频。
soft_hold
将已经成功bridge的通道挂起。
-
sound_test
将媒体流的包信息打印在控制台中（不会写入日志）。 -
speak
朗读一段文本（需用到TTS引擎）。 -
start_dtmf
在当前通道开启dtmf检测。不能和start_dtmf_generate一起用；和ring_ready一起用时要保证ring_ready在前。 -
start_dtmf_generate
允许在当前通道生成dtmf。 -
stop_displace_session
停止播放文件/音频，和displace_session功能是一对。 -
stop_dtmf
停止带内dtmf（inband dtmf）检测。延申：dtmf有三种模式：inband、sipinfo和rfc2833，根据实际来看，其中inband模式的识别率比较低，这是因为inband模式是把按键产生的信号和语音流一起传输的，同时解码是根据频谱分析进行的。 -
stop_dtmf_generate
禁止当前通道生成dtmf。 -
stop_record_session
停止录音。和record_session功能是一对。 -
stop_tone_detect
停止当前通道的tone检测。和tone_detect是一对。 -
strepoch
将当前时间转为整数（1970年1月1日至今的秒数）。一般用于需要判断时间的场景。 -
strftime
将当前时间显示为各种格式。具体用法见官网。 -
strftime_tz
和strftime类似，区别是这个功能支持不同时区。 -
strmicroepoch
和strepoch功能类似，区别是这个功能返回的是毫秒 -
system
执行一个系统命令并等待返回结果（阻塞的）。 -
three_way
三方通话功能，加入一个正在进行中的通话（已经bridged的通话）。这个功能是借助eavesdrop功能实现的。 -
tone_detect
tone检测。 -
transfer
转接。可能是最常见和核心的dptool了。将当前channel立刻转入一个新的路由（xml文件）。更多用法这里不赘述，参考官方文档。 -
unbind_meta_app
和bind_meta_app成对使用。如果用bind_meta_app绑了一个dtmf，那么使用unbind_meta_app后取消绑定（可以取消某个dtmf，也可以取消所有dtmf，具体使用见官方文档）。 -
unhold
和hold成对使用。 -
unset
和set成对使用。 -
verbose_events
“启用详细事件”。verbose events拥有全部的通道变量，而non-verbose events只拥有部分预先选定的通道变量。这个设置也可以在switch.conf.xml中开启或关闭。 -
wait_for_answer
等待session接通（接通后才继续执行dialplan）。 -
wait_for_silence
检测指定时长的静默。dialplan在检测到指定时长的静默或检测超时后，才会继续执行，否则暂停执行。