[freeswitch]mod_dptools功能总结（updating）

前言
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
  预定一个广播。例如一小时后向主被叫双方播放一段音频： 。预定成功后会设置通道变量last_sched_id。

• sched transfer
  预定一个转接。例如10分钟后将通话转入default.xml：
  。预定成功后会设置通道变量last_sched_id。

• sched cancel
  根据last_sched_id取消定时任务（由上面的sched broadcast或sched transfer设置的transfer或broadcast）。

• sched hungup
  定时挂断。可以用来限制呼叫时长。

• send_display
  发送一个信息包用于展示，如果终端支持的话会显示这个信息。

• send dtmf
  发送dtmf。例如：。@后的数字表示每个dtmf的持续时长(ms)，如果不指定这个时长，则默认2000ms。

• 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在检测到指定时长的静默或检测超时后，才会继续执行，否则暂停执行。