技術文章 » FreeSWITCH的originate命令解析及範例

FreeSWITCH的originate命令解析及範例

2023-04-03 06:00:27

FreeSWITCH版本：1.10.9

作業系統：CentOS 7.6.1810

originate經常用於發起呼叫，在實際工作過程中用到的也比較多，今天總結下基本用法，也方便我以後查閱。

一、wiki及原始碼介紹

該命令在FreeSWITCH官方wiki也有介紹，這裡列下wiki地址。

wiki首頁：https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/

originate相關wiki地址：

https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Dialplan/Freeswitch-IVR-Originate_9634753/#docusaurus_skipToContent_fallback

 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Examples/Originate-Example_10682745/#docusaurus_skipToContent_fallback

 原始碼檔案：mod_commands.c

對應函數：originate_function

 二、命令格式及解釋

命令使用的基礎模板：

originate ALEG BLEG

 在fs_cli控制檯使用的完整語法如下：

originate <call url> <exten>|&<application_name>(<app_args>) [<dialplan>][&lt;context>] [<cid_name>][&lt;cid_num>] [<timeout_sec>]

其中，

originate 為命令關鍵字，為必選欄位，用於定義ALEG的呼叫資訊，也就是通常說的呼叫字串，可以通過通道變數定義很多引數;

|&<application_name>(<app_args>)  為必選欄位，用於指定BLEG的分機號碼或者用於建立BLEG的app（比如echo、bridge等）;

[][<context>]  可選引數，該引數用於指定dialplan的context，預設值：xml default ;

[<timeout_sec>] 可選引數，該引數用於指定originate超時，預設值：60 ;

 範例呼叫：

originate user/1000 9196 xml default 'mike' 18612345678

呼叫效果如下：

 

 三、常見使用方式

1、基礎使用

  • echo呼叫

範例如下：

originate user/1000 &echo

先呼叫1000分機，1000分機接聽後，將1000分機所在的channel橋接到echo應用（將話筒傳入的聲音播放到聽筒），以下命令具備同樣效果：

originate user/1000 9196

  • 分機互相撥打

範例如下：

originate user/1000 1001

先呼叫1000分機，1000分機接聽後，再呼叫1001分機，1001分機接聽後，將1000分機所在的channel橋接1001的channel，通話建立。 

  • bridge到其它終端

這裡以分機為例進行演示，具體如下：

originate user/1000 &bridge(user/1001)

和分機互相撥打類似。

  • 分機共振

 使用逗號語法關鍵字，範例如下：

originate user/1000,user/1001 9196

1000分機和1001分機同時響鈴，任意一個分機接聽後，另外一個分機自動掛機。

  • 分機輪詢

 使用 | 語法實現，這裡需要注意下，有呼叫預設超時時間的設定，範例如下：

originate {originate_timeout=30}[leg_timeout=10]user/1000|[leg_timeout=10]user/1001 9196

1000分機先振鈴，10秒超時後呼叫1001分機。

  • 呼叫外線

通過external進行外線呼叫，範例如下：

originate  {origination_caller_id_number=00000000,origination_caller_id_name=000000000}sofia/external/18612345678@192.168.1.100:5060 &echo

  • 播放音訊給分機

使用playback命令進行聲音播放：

originate user/1000 &playback(/tmp/test1.wav)

播放moh音訊：

originate user/1000 &playback(local_stream://moh)

無限迴圈播放：

originate user/1000 &endless_playback(/tmp/test1.wav)

使用file_string進行多個檔案依次順序播放：

originate user/1000 &playback(file_string:///tmp/test1.wav!/tmp/test2.wav)

2、通道變數的使用

originate字串裡面可以設定很多通道變數來定義呼叫引數，基本使用格式範例如下：

originate {var1=$value1,var2=$value2}/user/1000 9196
originate {var1=$value1}[var2=$value2]/user/1000 9196

其中，大括號用於定義呼叫的通道變數，中括號用來定義某條leg的區域性通道變數。

這裡列舉下常見的通道變數。

  • origination_uuid

發起呼叫時，用於定義leg的uuid，範例如下：

1）在呼叫時，指定A腿的uuid

originate {origination_uuid=xxxxx}user/1000 1001

2）在呼叫時，同時指定A腿和B腿的uuid

originate {origination_uuid=xxxxx}user/1000 &bridge({origination_uuid=yyyyy}user/1001)

  • origination_caller_id_name / origination_caller_id_number

用於設定主叫名稱及號碼，範例如下：

originate {origination_caller_id_name="mike",origination_caller_id_number=18612345678}user/1000 9196

會在話機及sip協定中體現，具體如下:

 

  • ignore_early_media

該引數適用於A leg，定義是否忽略B leg的early media。

  • originate_timeout

用於定義originate/bridge過程中的呼叫時長，超過該時間後就呼叫超時。

範例參考分機輪詢部分。

  • leg_timeout

用於定義originate/bridge過程中某條leg的呼叫時長，超過該時間後就呼叫超時。

範例參考分機輪詢部分。

  • absolute_codec_string

用於指定語音編碼，範例如下：

originate {absolute_codec_string=‘^^:PCMA:PCMU’}user/1000 &playback(local_stream://moh)

其中，"^^"為跳脫符，後面跟冒號表示用冒號替代逗號。 

  • 自定義通道變數

在originate字串中可以自定義通道變數，範例如下：

originate {var123="test123"}user/1000 9196

效果如下：

 通道變數名稱會自動新增 variable_ 字首，具體來說就是 variable_var123

  • 更多通道變數

具體參考switch_ivr_originate函數（switch_ivr_originate.c檔案）

3、新增自定義sip頭

在originate字串中，可以自定義sip頭，通過新增 sip_h_X 字首來試下，範例如下： 

originate {sip_h_X-varTest='123456'}user/1000 &playback(local_stream://moh)

會在sip協定中新增自定義的header，具體效果如下：

4、特殊呼叫

  • loopback呼叫

1）撥號方案自帶的loopback

範例呼叫：

originate user/1000 &bridge(loopback/wait)

具體定義如下：

 2）自定義loopback

dialplan新增如下內容：

<extension name="loopback_test">
    <condition field="destination_number" expression="^loopTest1$">
         <action application="answer"/>
         <action application="playback" data="local_stream://moh"/>
    </condition>
</extension>

呼叫測試：

originate user/1000 &bridge(loopback/loopTest1)

  • null呼叫

呼叫範例：

originate null/1000 &echo

具體效果：

 也可以和bridge一起使用：

originate user/1000 &bridge(null/1234)

具體效果：

  • 其它endpoint呼叫

這裡以rtc為例，演示其它endpoint呼叫：

bgapi originate {origination_uuid=111222}rtc/test &echo

具體效果如下：

  • 指定sip使用tcp協定呼叫

需要使用 transport=tcp 來指定協定，範例如下：

originate {origination_caller_id_name=1111}user/1000;transport=tcp  &playback(local_stream://moh)

效果如下：

四、資源下載

本文涉及freeswitch原始碼及使用的測試軟電話可從如下渠道獲取：

https://pan.baidu.com/s/16-H-ITuXAcPYRsZpa3At-g

關注微信公眾號（聊聊博文，文末可掃碼）後回覆 2023040201 獲取。