FreeSWITCH新增自定義endpoint

作業系統：CentOS 7.6_x64

FreeSWITCH版本：1.10.9

日常開發過程中會遇到需要擴充套件FreeSWITCH對接其它系統的情況，這裡記錄下編寫FreeSWITCH自定義endpoint的過程。

一、模組定義函數

使用FreeSWITCH自帶的框架來定義模組函數，函數指標及參數列定義如下（src/include/switch_types.h）

#define SWITCH_MODULE_LOAD_ARGS (switch_loadable_module_interface_t **module_interface, switch_memory_pool_t *pool)
#define SWITCH_MODULE_RUNTIME_ARGS (void)
#define SWITCH_MODULE_SHUTDOWN_ARGS (void)
typedef switch_status_t (*switch_module_load_t) SWITCH_MODULE_LOAD_ARGS;
typedef switch_status_t (*switch_module_runtime_t) SWITCH_MODULE_RUNTIME_ARGS;
typedef switch_status_t (*switch_module_shutdown_t) SWITCH_MODULE_SHUTDOWN_ARGS;
#define SWITCH_MODULE_LOAD_FUNCTION(name) switch_status_t name SWITCH_MODULE_LOAD_ARGS
#define SWITCH_MODULE_RUNTIME_FUNCTION(name) switch_status_t name SWITCH_MODULE_RUNTIME_ARGS
#define SWITCH_MODULE_SHUTDOWN_FUNCTION(name) switch_status_t name SWITCH_MODULE_SHUTDOWN_ARGS

1、模組載入

SWITCH_MODULE_LOAD_FUNCTION

模組載入函數，負責系統啟動時或執行時載入模組，可以進行設定讀取及資源初始化。

2、模組解除安裝

SWITCH_MODULE_SHUTDOWN_FUNCTION

模組解除安裝函數，負載模組解除安裝及相關資源回收。

3、模組執行時

SWITCH_MODULE_RUNTIME_FUNCTION

模組執行時函數，可以啟動執行緒處理請求，監聽socket等。

4、模組定義

SWITCH_MODULE_DEFINITION

相關程式碼：

typedef struct switch_loadable_module_function_table {
    int switch_api_version;
    switch_module_load_t load;
    switch_module_shutdown_t shutdown;
    switch_module_runtime_t runtime;
    switch_module_flag_t flags;
} switch_loadable_module_function_table_t;

#define SWITCH_MODULE_DEFINITION_EX(name, load, shutdown, runtime, flags)                   \
static const char modname[] =  #name ;                                                      \
SWITCH_MOD_DECLARE_DATA switch_loadable_module_function_table_t name##_module_interface = { \
    SWITCH_API_VERSION,                                                                     \
    load,                                                                                   \
    shutdown,                                                                               \
    runtime,                                                                                \
    flags                                                                                   \
}

#define SWITCH_MODULE_DEFINITION(name, load, shutdown, runtime)                             \
        SWITCH_MODULE_DEFINITION_EX(name, load, shutdown, runtime, SMODF_NONE)

二、模組載入流程

FreeSWITCH使用 switch_loadable_module_load_module 或 switch_loadable_module_load_module_ex 進行模組載入，具體實現邏輯可以在 switch_loadable_module.c 中檢視，這裡做下簡單介紹。

1、模組載入函數

通過 switch_loadable_module_load_module 函數載入模組，函數呼叫鏈如下：

switch_loadable_module_load_module 
        => switch_loadable_module_load_module_ex  
        => switch_loadable_module_load_file
            => switch_loadable_module_process
            => switch_core_launch_thread  =>  switch_loadable_module_exec

通過 switch_dso_data_sym 根據定義的 XXX_module_interface 從動態庫裡面獲取回撥函數指標，使用 switch_loadable_module_function_table_t 資料結構進行回撥函數繫結。

switch_dso_data_sym 函數實現如下（src/switch_dso.c)：

void *switch_dso_data_sym(switch_dso_lib_t lib, const char *sym, char **err)
{
    void *addr = dlsym(lib, sym);
    if (!addr) {
        char *err_str = NULL;
        dlerror();

        if (!(addr = dlsym(lib, sym))) {
            err_str = (char *)dlerror();
        }

        if (err_str) {
            *err = strdup(err_str);
        }
    }
    return addr;
}

switch_loadable_module_exec函數：

static void *SWITCH_THREAD_FUNC switch_loadable_module_exec(switch_thread_t *thread, void *obj)
{


    switch_status_t status = SWITCH_STATUS_SUCCESS;
    switch_core_thread_session_t *ts = obj;
    switch_loadable_module_t *module = ts->objs[0];
    int restarts;

    switch_assert(thread != NULL);
    switch_assert(module != NULL);

    for (restarts = 0; status != SWITCH_STATUS_TERM && !module->shutting_down; restarts++) {
        status = module->switch_module_runtime();
    }
    switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_NOTICE, "Thread ended for %s\n", module->module_interface->module_name);

    if (ts->pool) {
        switch_memory_pool_t *pool = ts->pool;
        switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_DEBUG, "Destroying Pool for %s\n", module->module_interface->module_name);
        switch_core_destroy_memory_pool(&pool);
    }
    switch_thread_exit(thread, 0);
    return NULL;
}

switch_loadable_module_exec 函數為獨立執行緒中執行，模組執行時通過 module->switch_module_runtime() 觸發。

2、FreeSWITCH啟動時載入模組

1)整體結構

函數呼叫鏈如下：

main 
    => switch_core_init_and_modload 
        => switch_core_init
        => switch_loadable_module_init => switch_loadable_module_load_module

main函數在switch.c中實現。

2)載入順序

先載入系統核心模組：

switch_loadable_module_load_module_ex("", "CORE_SOFTTIMER_MODULE", SWITCH_FALSE, SWITCH_FALSE, &err, SWITCH_LOADABLE_MODULE_TYPE_COMMON, event_hash);
switch_loadable_module_load_module_ex("", "CORE_PCM_MODULE", SWITCH_FALSE, SWITCH_FALSE, &err, SWITCH_LOADABLE_MODULE_TYPE_COMMON, event_hash);
switch_loadable_module_load_module_ex("", "CORE_SPEEX_MODULE", SWITCH_FALSE, SWITCH_FALSE, &err, SWITCH_LOADABLE_MODULE_TYPE_COMMON, event_hash);

使用 switch_xml_open_cfg 函數（src/switch_xml.c中定義）先後載入以下檔案中定義的模組：

pre_load_modules.conf

modules.conf

post_load_modules.conf

具體格式參考 conf/autoload_configs/modules.conf.xml

3）xml載入過程

函數呼叫鏈如下：

main => switch_core_init_and_modload 
        => switch_core_init 
            => switch_xml_init 
                => switch_xml_open_root => XML_OPEN_ROOT_FUNCTION

其中 SWITCH_GLOBAL_filenames 變數定義如下（main => switch_core_set_globals）：

if (!SWITCH_GLOBAL_filenames.conf_name && (SWITCH_GLOBAL_filenames.conf_name = (char *) malloc(BUFSIZE))) {
        switch_snprintf(SWITCH_GLOBAL_filenames.conf_name, BUFSIZE, "%s", "freeswitch.xml");
}

XML_OPEN_ROOT_FUNCTION實現如下（src/switch_xml.c）：

static switch_xml_open_root_function_t XML_OPEN_ROOT_FUNCTION = (switch_xml_open_root_function_t)__switch_xml_open_root;

SWITCH_DECLARE_NONSTD(switch_xml_t) __switch_xml_open_root(uint8_t reload, const char **err, void *user_data)
{
    char path_buf[1024];
    uint8_t errcnt = 0;
    switch_xml_t new_main, r = NULL;

    if (MAIN_XML_ROOT) {
        if (!reload) {
            r = switch_xml_root();
            goto done;
        }
    }

    switch_snprintf(path_buf, sizeof(path_buf), "%s%s%s", SWITCH_GLOBAL_dirs.conf_dir, SWITCH_PATH_SEPARATOR, SWITCH_GLOBAL_filenames.conf_name);
    if ((new_main = switch_xml_parse_file(path_buf))) {
        *err = switch_xml_error(new_main);
        switch_copy_string(not_so_threadsafe_error_buffer, *err, sizeof(not_so_threadsafe_error_buffer));
        *err = not_so_threadsafe_error_buffer;
        if (!zstr(*err)) {
            switch_xml_free(new_main);
            new_main = NULL;
            errcnt++;
        } else {
            *err = "Success";
            switch_xml_set_root(new_main);

        }
    } else {
        *err = "Cannot Open log directory or XML Root!";
        errcnt++;
    }

    if (errcnt == 0) {
        r = switch_xml_root();
    }

 done:

    return r;
}

freeswitch.xml 為xml檔案的總入口，設定的有載入各個模組的資料：

<section name="configuration" description="Various Configuration">
    <X-PRE-PROCESS cmd="include" data="autoload_configs/*.xml"/>
</section>

3、控制檯動態載入

在fs_cli中可以使用load及reload載入模組，具體流程如下：

fs_cli => load ... => SWITCH_STANDARD_API(load_function) => switch_loadable_module_load_module 

fs_cli => reload ... => SWITCH_STANDARD_API(reload_function) => switch_loadable_module_unload_module 
                                                             => switch_loadable_module_load_module

三、關鍵資料結構

1、switch_loadable_module_t

作用：用於定義模組資訊。

結構體定義：

struct switch_loadable_module {
    char *key;
    char *filename;
    int perm;
    switch_loadable_module_interface_t *module_interface;
    switch_dso_lib_t lib;
    switch_module_load_t switch_module_load;
    switch_module_runtime_t switch_module_runtime;
    switch_module_shutdown_t switch_module_shutdown;
    switch_memory_pool_t *pool;
    switch_status_t status;
    switch_thread_t *thread;
    switch_bool_t shutting_down;
    switch_loadable_module_type_t type;
};

typedef struct switch_loadable_module switch_loadable_module_t;

欄位解釋：

key =》模組檔名稱

filename => 模組檔案路徑（動態庫路徑）

perm =》定義模組是否允許被解除安裝

module_interface =》模組介面（由switch_module_load函數賦值）

lib =》動態庫控制程式碼（dlopen函數返回）

switch_module_load =》模組載入函數

switch_module_runtime =》模組執行時函數

switch_module_shutdown =》模組關閉（解除安裝）函數

pool =》模組記憶體池

status =》 switch_module_shutdown 函數的返回值

shutting_down => 模組是否關閉

2、switch_loadable_module_interface

作用：模組介面（入口）

結構體定義：

struct switch_loadable_module_interface {
    /*! the name of the module */
    const char *module_name;
    /*! the table of endpoints the module has implemented */
    switch_endpoint_interface_t *endpoint_interface;
    /*! the table of timers the module has implemented */
    switch_timer_interface_t *timer_interface;
    /*! the table of dialplans the module has implemented */
    switch_dialplan_interface_t *dialplan_interface;
    /*! the table of codecs the module has implemented */
    switch_codec_interface_t *codec_interface;
    /*! the table of applications the module has implemented */
    switch_application_interface_t *application_interface;
    /*! the table of chat applications the module has implemented */
    switch_chat_application_interface_t *chat_application_interface;
    /*! the table of api functions the module has implemented */
    switch_api_interface_t *api_interface;
    /*! the table of json api functions the module has implemented */
    switch_json_api_interface_t *json_api_interface;
    /*! the table of file formats the module has implemented */
    switch_file_interface_t *file_interface;
    /*! the table of speech interfaces the module has implemented */
    switch_speech_interface_t *speech_interface;
    /*! the table of directory interfaces the module has implemented */
    switch_directory_interface_t *directory_interface;
    /*! the table of chat interfaces the module has implemented */
    switch_chat_interface_t *chat_interface;
    /*! the table of say interfaces the module has implemented */
    switch_say_interface_t *say_interface;
    /*! the table of asr interfaces the module has implemented */
    switch_asr_interface_t *asr_interface;
    /*! the table of management interfaces the module has implemented */
    switch_management_interface_t *management_interface;
    /*! the table of limit interfaces the module has implemented */
    switch_limit_interface_t *limit_interface;
    /*! the table of database interfaces the module has implemented */
    switch_database_interface_t *database_interface;
    switch_thread_rwlock_t *rwlock;
    int refs;
    switch_memory_pool_t *pool;
};

typedef struct switch_loadable_module_interface switch_loadable_module_interface_t;

欄位解釋：

module_name => 模組的名稱

endpoint_interface => 模組endpoint的具體實現

timer_interface => 模組timer的具體實現

dialplan_interface => 模組dialplan的具體實現

codec_interface => 模組編解碼的具體實現

application_interface => 模組提供的app工具的具體實現

chat_application_interface => 模組提供的文字聊天app工具的具體實現

api_interface => 模組提供的api具體實現

json_api_interface => 模組提供的json格式api的具體實現

file_interface => 模組支援的檔案格式的具體實現（比如mp4、mkv等檔案格式）

speech_interface => 模組使用的speech介面實現

directory_interface => 模組使用的directory介面實現

chat_interface => 模組使用的chat介面實現

say_interface => 模組使用的say介面實現

asr_interface => 模組使用的asr介面實現

management_interface => 模組使用的管理介面實現

limit_interface => 模組使用的limit介面實現

database_interface => 模組使用的limit介面實現

rwlock => 模組使用的鎖

refs => 模組鎖的計數器

pool =》模組記憶體池

使用 switch_loadable_module_create_module_interface 來建立 switch_loadable_module_interface_t 範例。

SWITCH_DECLARE(switch_loadable_module_interface_t *) switch_loadable_module_create_module_interface(switch_memory_pool_t *pool, const char *name)
{
    switch_loadable_module_interface_t *mod;

    mod = switch_core_alloc(pool, sizeof(switch_loadable_module_interface_t));
    switch_assert(mod != NULL);

    mod->pool = pool;

    mod->module_name = switch_core_strdup(mod->pool, name);
    switch_thread_rwlock_create(&mod->rwlock, mod->pool);
    return mod;
}

使用 switch_loadable_module_create_interface 來建立模組裡面的子介面，範例如下：

*module_interface = switch_loadable_module_create_module_interface(pool, modname);

rtc_endpoint_interface = switch_loadable_module_create_interface(*module_interface, SWITCH_ENDPOINT_INTERFACE);
rtc_endpoint_interface->interface_name = "rtc";
rtc_endpoint_interface->io_routines = &rtc_io_routines;
rtc_endpoint_interface->state_handler = &rtc_event_handlers;
rtc_endpoint_interface->recover_callback = rtc_recover_callback;

具體實現如下：

SWITCH_DECLARE(void *) switch_loadable_module_create_interface(switch_loadable_module_interface_t *mod, switch_module_interface_name_t iname)
{

    switch (iname) {
    case SWITCH_ENDPOINT_INTERFACE:
        ALLOC_INTERFACE(endpoint)

    case SWITCH_TIMER_INTERFACE:
        ALLOC_INTERFACE(timer)

    case SWITCH_DIALPLAN_INTERFACE:
        ALLOC_INTERFACE(dialplan)

    case SWITCH_CODEC_INTERFACE:
        ALLOC_INTERFACE(codec)

    case SWITCH_APPLICATION_INTERFACE:
        ALLOC_INTERFACE(application)

    case SWITCH_CHAT_APPLICATION_INTERFACE:
        ALLOC_INTERFACE(chat_application)

    case SWITCH_API_INTERFACE:
        ALLOC_INTERFACE(api)

    case SWITCH_JSON_API_INTERFACE:
        ALLOC_INTERFACE(json_api)

    case SWITCH_FILE_INTERFACE:
        ALLOC_INTERFACE(file)

    case SWITCH_SPEECH_INTERFACE:
        ALLOC_INTERFACE(speech)

    case SWITCH_DIRECTORY_INTERFACE:
        ALLOC_INTERFACE(directory)

    case SWITCH_CHAT_INTERFACE:
        ALLOC_INTERFACE(chat)

    case SWITCH_SAY_INTERFACE:
        ALLOC_INTERFACE(say)

    case SWITCH_ASR_INTERFACE:
        ALLOC_INTERFACE(asr)

    case SWITCH_MANAGEMENT_INTERFACE:
        ALLOC_INTERFACE(management)

    case SWITCH_LIMIT_INTERFACE:
        ALLOC_INTERFACE(limit)

    case SWITCH_DATABASE_INTERFACE:
        ALLOC_INTERFACE(database)

    default:
        switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_WARNING, "Invalid Module Type!\n");
        return NULL;
    }
}

3、switch_endpoint_interface_t

作用：endpoint的入口

結構體定義：

struct switch_endpoint_interface {
    /*! the interface's name */
    const char *interface_name;

    /*! channel abstraction methods */
    switch_io_routines_t *io_routines;

    /*! state machine methods */
    switch_state_handler_table_t *state_handler;

    /*! private information */
    void *private_info;

    switch_thread_rwlock_t *rwlock;
    int refs;
    switch_mutex_t *reflock;

    /* parent */
    switch_loadable_module_interface_t *parent;

    /* to facilitate linking */
    struct switch_endpoint_interface *next;

    switch_core_recover_callback_t recover_callback;

};

typedef struct switch_endpoint_interface switch_endpoint_interface_t;

欄位解釋：

interface_name => endpoint名稱，比如："rtc"

io_routines => endpoint對應的io操作回撥函數

state_handler => endpoint對應的事件處理回撥函數

private_info => endpoint私有引數設定（比如編碼格式、取樣率等）

rwlock => endpoint鎖

refs => endpoint鎖的參照次數

reflock => endpoint參照鎖

parent => endpoint所屬模組

next => next指標

recover_callback => endpoint對應的recover回撥函數

4、switch_io_routines

作用：儲存io操作的回撥函數

結構體定義：

struct switch_io_routines {
    /*! creates an outgoing session from given session, caller profile */
    switch_io_outgoing_channel_t outgoing_channel;
    /*! read a frame from a session */
    switch_io_read_frame_t read_frame;
    /*! write a frame to a session */
    switch_io_write_frame_t write_frame;
    /*! send a kill signal to the session's channel */
    switch_io_kill_channel_t kill_channel;
    /*! send a string of DTMF digits to a session's channel */
    switch_io_send_dtmf_t send_dtmf;
    /*! receive a message from another session */
    switch_io_receive_message_t receive_message;
    /*! queue a message for another session */
    switch_io_receive_event_t receive_event;
    /*! change a sessions channel state */
    switch_io_state_change_t state_change;
    /*! read a video frame from a session */
    switch_io_read_video_frame_t read_video_frame;
    /*! write a video frame to a session */
    switch_io_write_video_frame_t write_video_frame;
    /*! read a video frame from a session */
    switch_io_read_text_frame_t read_text_frame;
    /*! write a video frame to a session */
    switch_io_write_text_frame_t write_text_frame;
    /*! change a sessions channel run state */
    switch_io_state_run_t state_run;
    /*! get sessions jitterbuffer */
    switch_io_get_jb_t get_jb;
    void *padding[10];
};

typedef struct switch_io_routines switch_io_routines_t;

欄位解釋：

outgoing_channel => 建立外呼channel的回撥函數

read_frame => 讀session音訊資料的回撥函數

write_frame => 寫session音訊資料的回撥函數

kill_channel => kill訊號處理常式，用於處理channel接收的kill訊號

send_dtmf => send dtmf操作的回撥函數，用於處理channel接收的DTMF字串

receive_message => 處理channel訊息的回撥函數，用於處理其它channel發來的訊息

receive_event => 傳送channel訊息的回撥函數，用於向目標session傳送自定義事件（比如rtc session、rtmp session等）

state_change => channel狀態修改的回撥函數

read_video_frame => 讀session視訊資料的回撥函數

write_video_frame => 寫session視訊資料的回撥函數

read_text_frame => 讀session文字資料的回撥函數

write_text_frame => 寫session文字資料的回撥函數

state_run => 改變session的執行狀態，目前沒見到有endpoint使用過

get_jb => 獲取session的jitter_buffer

5、switch_state_handler_table_t

作用：用於儲存狀態機的回撥函數。

定義如下：

struct switch_state_handler_table {
    /*! executed when the state changes to init */
    switch_state_handler_t on_init;
    /*! executed when the state changes to routing */
    switch_state_handler_t on_routing;
    /*! executed when the state changes to execute */
    switch_state_handler_t on_execute;
    /*! executed when the state changes to hangup */
    switch_state_handler_t on_hangup;
    /*! executed when the state changes to exchange_media */
    switch_state_handler_t on_exchange_media;
    /*! executed when the state changes to soft_execute */
    switch_state_handler_t on_soft_execute;
    /*! executed when the state changes to consume_media */
    switch_state_handler_t on_consume_media;
    /*! executed when the state changes to hibernate */
    switch_state_handler_t on_hibernate;
    /*! executed when the state changes to reset */
    switch_state_handler_t on_reset;
    /*! executed when the state changes to park */
    switch_state_handler_t on_park;
    /*! executed when the state changes to reporting */
    switch_state_handler_t on_reporting;
    /*! executed when the state changes to destroy */
    switch_state_handler_t on_destroy;
    int flags;
    void *padding[10];
};


typedef struct switch_state_handler_table switch_state_handler_table_t;

引數解釋：

on_init => channel進入 CS_INIT 狀態的回撥函數

on_routing => channel進入 CS_ROUTING 狀態的回撥函數

on_execute => channel進入 CS_EXECUTE 狀態的回撥函數，用於執行操作

on_hangup => channel進入 CS_HANGUP 狀態的回撥函數

on_exchange_media => channel進入 CS_EXCHANGE_MEDIA 狀態的回撥函數

on_soft_execute => channel進入 CS_SOFT_EXECUTE 狀態的回撥函數，用於從其它channel接收或傳送資料

on_consume_media => channel進入 CS_CONSUME_MEDIA 狀態的回撥函數，

on_hibernate => channel進入 CS_HIBERNATE 狀態的回撥函數，sleep操作

on_reset => channel進入 CS_RESET 狀態的回撥函數

on_park => channel進入 CS_PARK 狀態的回撥函數

on_reporting => channel進入 CS_REPORTING 狀態的回撥函數

on_destroy => channel進入 CS_DESTROY 狀態的回撥函數

switch_core_state_machine.c中使用 STATE_MACRO 觸發，部分觸發程式碼如下：

case CS_ROUTING:    /* Look for a dialplan and find something to do */
    STATE_MACRO(routing, "ROUTING");
    break;
case CS_RESET:        /* Reset */
    STATE_MACRO(reset, "RESET");
    break;
    /* These other states are intended for prolonged durations so we do not signal lock for them */
case CS_EXECUTE:    /* Execute an Operation */
    STATE_MACRO(execute, "EXECUTE");
    break;
case CS_EXCHANGE_MEDIA:    /* loop all data back to source */
    STATE_MACRO(exchange_media, "EXCHANGE_MEDIA");
    break;
case CS_SOFT_EXECUTE:    /* send/recieve data to/from another channel */
    STATE_MACRO(soft_execute, "SOFT_EXECUTE");
    break;
case CS_PARK:        /* wait in limbo */
    STATE_MACRO(park, "PARK");
    break;
case CS_CONSUME_MEDIA:    /* wait in limbo */
    STATE_MACRO(consume_media, "CONSUME_MEDIA");
    break;
case CS_HIBERNATE:    /* sleep */
    STATE_MACRO(hibernate, "HIBERNATE");
    break;