Liblinphone 3.9.1中文--Modules--Managing proxies_linphone_proxy_config_enable_register

Managing proxies 管理代理

 

 宏

    #define linphone_proxy_config_expires  linphone_proxy_config_set_expires

    #define linphone_proxy_config_enableregister  linphone_proxy_config_enable_register

    #define linphone_proxy_config_get_addr   linphone_proxy_config_get_server_addr

    #define linphone_core_set_default_proxy(lc, config)   linphone_core_set_default_proxy_config(lc, config)

类型定义

           typedef struct _LinphoneProxyConfig LinphoneProxyConfig

      typedef  enum  _LinphonRegistrationState LinphoneRegistrationState

枚举类型

     enum  _LinphoneRegistrationState{

            LinphoneRegistrationNone,

            LinphoneRegistrationProgress,

            LinphoneRegistrationOk,

            LinphoneRegistrationCleared,

            LinphoneRegistrationFailed

          }

函数

详细说明

     用户注册是由LinphoneProxyConfig设置控制.

     每一个LinphoneProxyConfig对象可用被配置一些注册信息例如代理地址、用户id、刷新时间等等.

     用linphone_proxy_config_new()创建一个代理配置，一旦配置完成，必须被添加到LinphoneCore通过函数linphone_core_add_proxy_config().

     建议使用函数linphone_core_set_default_proxy().一旦完成，如果代理配置已经配置了属性启用注册，然后调用linphone_core_iterate()触发SIP登记

     注册状态由LinphoneCoreRegistrationStateChangedCb通知. 

     下面的伪代码演示了基本的注册操作：

LinphoneProxyConfig* proxy_cfg;
/*create proxy config*/
proxy_cfg = linphone_proxy_config_new();
/*parse identity*/
LinphoneAddress *from = linphone_address_new("sip:toto@sip.titi.com");
LinphoneAuthInfo *info;
if (password!=NULL){
        info=linphone_auth_info_new(linphone_address_get_username(from),NULL,"secret",NULL,NULL); /*create authentication structure from identity*/
        linphone_core_add_auth_info(lc,info); /*add authentication info to LinphoneCore*/
}
// configure proxy entries
linphone_proxy_config_set_identity(proxy_cfg,identity); /*set identity with user name and domain*/
const char* server_addr = linphone_address_get_domain(from); /*extract domain address from identity*/
linphone_proxy_config_set_server_addr(proxy_cfg,server_addr); /* we assume domain = proxy server address*/
linphone_proxy_config_enable_register(proxy_cfg,TRUE); /*activate registration for this proxy config*/
linphone_address_destroy(from); /*release resource*/
linphone_core_add_proxy_config(lc,proxy_cfg); /*add proxy config to linphone core*/
linphone_core_set_default_proxy(lc,proxy_cfg); /*set to default proxy*/ 

登记状态回调：

   

 static void registration_state_changed(struct _LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message){
                printf("New registration state %s for user id [%s] at proxy [%s]\n"
                                ,linphone_registration_state_to_string(cstate)
                                ,linphone_proxy_config_get_identity(cfg)
                                ,linphone_proxy_config_get_addr(cfg));
}

身份验证：

     通常，登记需要身份认证成功.在LinphoneProxyConfig被添加到LinphoneCore之前，LinphoneAuthInfo信息必须使用函数linphone_core_add_auth_info添加到LinphoneCore,或者按LinphoneCoreAuthInfoRequestedCb回调的要求

注销：

     注销或者变更LinphoneProxyConfig 必须首先由调用linphone_proxy_config_edit() 并且由linphone_proxy_config_done()来验证.

     下面伪代码展示了如何注销一个关联到LinphoneProxyConfig上的用户.  

     

LinphoneProxyConfig* proxy_cfg;
linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/
linphone_proxy_config_edit(proxy_cfg); /*start editing proxy configuration*/
linphone_proxy_config_enable_register(proxy_cfg,FALSE); /*de-activate registration for this proxy config*/
linphone_proxy_config_done(proxy_cfg); /*initiate REGISTER with expire = 0*/

      一个完整的教程： Registration tutorial

宏定义文档

         #define linphone_core_set_default_proxy(lc, config)

     已弃用：

            用linphone_core_set_default_proxy_config()代替

自定义文档

      typedef struct _LinphoneProxyConfig LinphoneProxyConfig

      LinphoneProxyConfig对象代表供LinphoneCore使用的代理配置.它的域不允许被直接使用，需要访问器方法.一旦正确地创建和填充好LinphoneProxyConfig可以通过linphone_core_add_proxy_config()添加到LinphoneCore.如果启用，这将自动触发注册.

      代理配置需要持久重启，因为他们要被保存到配置文件中.因此，在linphone_core_new()之后，可能这里已经有一个已配置代理的列表，这可以由linphone_core_get_proxy_config_list()检查.

      默认代理（参见linphone_core_set_default_proxy()）是代理列表中被默认用来通话的哪一个.

typedef enum _LinphoneRegistrationState   LinphoneRegistrationState

      LinphoneRegistrationState描述了代理注册状态

枚举类型的文档

     enum _LinphoneRegistrationState

      LinphoneRegistrationState 描述了代理注册状态

      枚举成员

               LinphoneRegistrationNone         注册的初始状态

               LinphoneRegistrationProgress     正在注册中

               LinphoneRegistrationOk           注册成功

               LinphoneRegistrationCleared      注销成功

               LinphoneRegistrationFailed       注册失败

函数文档

      int linphone_core_add_proxy_config(LinphoneCore* lc, LinphoneProxyConfig* config)

       添加一个代理配置.这将启动注册代理，如果启用了注册.

       void linphone_core_clear_proxy_config(LinphoneCore* lc)

       从配置中删除所有代理

       LinphoneProxyConfig* linphone_core_create_proxy_config(LinphoneCore* lc)

       添加一个默认参数的代理配置.

       参数   

                [in]lc LinphoneCore对象

       返回

                被设置默认值的LinphoneProxyConfig对象

MS2_DEPRECATED int linphone_core_get_default_proxy(LinphoneCore* lc, LinphoneProxyConfig** config)

       返回 

                默认代理配置，这个是被用来确认当前身份的一个代理配置

       已弃用

                使用linphone_core_get_default_proxy_config()替代

LinphoneProxyConfig* linphone_core_get_default_proxy_config(LinphoneCore* lc)

      返回 

            默认的代理配置，这是被用来确认当前身份的一个代理配置

      参数

              [in] lc LinphoneCore对象

      返回  

              默认的代理配置

 bool_t linphone_core_get_guess_hostname(LinphoneCore* lc)

       如果主联系的主机名部分被自动解析.返回TRUE

const char* linphone_core_get_identity(LinphoneCore* lc)

       返回默认的身份SIP地址

      这是一个助手函数：

       如果没有设置默认代理，这将返回主联系（参见linphone_core_get_primary_contact()）.如果设置了一个默认代理，它返回已注册的代理身份.

const char* linphone_core_get_primary_contact(LinphoneCore* lc)

      当没有代理配置可用时，返回默认的身份

LinphoneAddress* linphone_core_get_primary_contact_parsed(LinphoneCore* lc)

      等同于linphone_core_get_primary_contact(),但是返回的是一个LinponeAddress对象而不是一个const char*

const bctbx_list_t*  linphone_core_get_proxy_config_list(const LinphoneCore* lc)

      返回一个不可变的关于输入代理配置的列表

      参数

             [in] lc LinphoneCore对象

      返回

              LinphoneProxyConfig对象链表

void linphone_core_refresh_registers(LinphoneCore* lc)

     在下一次迭代中，强制刷新注册初始化

void linphone_core_remove_proxy_config(LinphoneCore* lc, LinphoneProxyConfig* config)

      移除一个代理配置

      LinphoneCore会自动地注销并将代理配置放到一个删除列表.出于这个原因，移除代理不需要释放

void linphone_core_set_default_proxy_config(LinphoneCore* lc, LinphoneProxyConfig* config)

      设置默认代理

      这个默认代理必须是已经加入到LinphoneProxyConfig列表中的成员.切换默认代理会让LinphoneCor用和该代理配置相关联的身份，在所有传入和传出的电话中

      参数

              [in] LinphoneCore对象

              [in] config 作为默认的代理配置

void linphone_core_set_guess_hostname(LinphoneCore* lc, bool_t val)

      让LinphoneCore自动地从主联系上推测本地本机名

int linphone_core_set_primary_contact(LinphoneCore* lc, const char* contact)

      设置本地的“from”身份

      这个数据用于没有任何代理配置，或者没有设置默认代理配置时，参见LinphoneProxyConfig

bool_t linphone_proxy_config_avpf_enabled(LinphoneProxyConfig* cfg)

      判断AVPF/SAVPF是否被用于通话,通过使用这个代理配置

      参数

            [in]cfg LinphoneProxyConfig对象

      返回

             如果AVPF/SAVPF可用，返回TRUE, 否则返回false

      已弃用：

             使用 linphone_proxy_config_set_avpf_mode()代替

void linphone_proxy_config_destroy(LinphonProxyConfig* cfg)

      销毁代理配置

      已弃用:

             LinphoneProxyConfig已经由LinphoneCore用linphone_core_remove_proxy_config()移除，不一定要释放.

int linphone_proxy_config_done(LinphoneProxyConfig* cfg)

    提交代理配置的修改

void linphone_proxy_config_edit(LinphonProxyConfig* cfg)  

    开始编辑一个代理配置

    因为代理配置必须是一致的，在做任何尝试来修改代理配置（例如 身份，代理位置，等等）之前，应用程序必须调用linphone_proxy_config_edit().一旦修改完成，那么应用程序必须调用linphone_proxy_config_done()来提交更改.

void linphone_proxy_config_enable_avpf(LinphoneProxyConfig* cfg, bool_t enable)

      是否启用AVPF/SAVPF在通话中

     参数

            [in]cfg LinphoneProxyConfig对象

            [in]enable True是启用AVPF/SAVF, FALSE 是弃用它

     已弃用：

             使用linphone_proxy_config_set_avpf_mode()

void linphone_proxy_config_enable_publish(LinphoneProxyConfig* cfg, bool_t val)

     表明PUBLISH是否必须为这个LinphoneProxyConfig发布.以防LinphoneProxyConfig已经添加到LinphoneCore，遵循linphone_proxy_config_edit()规则.

     参数

           [in] cfg LinphoneProxyConfig对象

                val 如果为true,PUBLISH会被占用.

void linphone_proxy_config_enable_quality_reporting(LinphonProxyConfig* cfg, bool_t enable)

     表明在通话过程中，质量统计数据是否应该被保存并发送到一个收集器，根据RFC 6035

     参数

           [in] cfg LinphoneProxyConfig对象

           [in] enable True是保存质量统计数据并发送到收集器，False是禁用该功能

void linphone_proxy_config_enable_register(LinphoneProxyConfig* cfg, bool_t val)

        表明REGISTRATION必须为这个LinphoneProxyConfig发布. 万一这个LinphoneProxyConfig已经加入了LinphoneCore，则需要遵循linphone_proxy_config_edit()规则.

      参数

              [in] cfg LinphoneProxyConfig对象

                   val 如果TRUE,REGISTRATION会被占用

const LinphoneAuthInfo* linphone_proxy_config_find_auth_info(const LinphoneProxyConfig* cfg)

       查找匹配代理配置的身份验证信息，如果有的话，类似于linphone_core_find_auth_info.

       参数

              [in] cfg LinphoneProxyConfig对象

       返回

              一个与cfg匹配的LinphoneAuthInfo对象，如果找不到，返回NULL

LinphoneAVPFMode linphone_proxy_config_get_avpf_mode(const LinphoneProxyConfig* cfg)

      获取RTCP反馈的启用状态（也称为AVPF概要文件）

      参数

               [in] cfg LinphoneProxyConfig对象

      返回

               支持模式有 LinphoneAVPFDefault(用LinphoneCore的模式)，LinphoneAVPFEnabled(avpf启用)，LinphoneAVPFDisabled(禁用)

uint8_t linphone_proxy_config_get_avpf_rr_interval(const LinphoneProxyConfig* cfg)

     在使用AVPF/SAVPF时，获取正常的RTCP报告的时间间隔

     参数

           [in] cfg LinphoneProxyConfig对象

     返回

           时间间隔,秒为单位

const char* linphone_proxy_config_get_contact_parameters(const LinphoneProxyConfig* cfg)

     返回

           预先设置的联系参数

const char* linphone_proxy_config_get_contact_uri_parameters(const LinphoneProxyConfig* cfg)

     返回

          预先设置的联系的URI参数

LinphoneCore* linphone_proxy_config_get_core(const LinphoneProxyConfig* cfg)

     获取与LinphoneProxyConfig相关联的LinphoneCore对象

     参数

             [in] cfg LinphoneProxyConfig对象

     返回

             相关的LinphoneCore对象

const char* linphone_proxy_config_get_custom_header(LinphoneProxyConfig* cfg, const char* header_name)

      获取一个报头的值，该头是由服务器在最近一次答复REGISTER时发送的.

      参数

             [in] cfg  LinphoneProxyConfig对象

                  header_name 用报头名字获取相应的值

      返回

             所查询报头的值

bool_t linphone_proxy_config_get_dial_escape_plus(const LinphoneProxyConfig* cfg)

      返回

            linphone是否应该用“00”代替“+”（）在拨打号码时（传递给linphone_core_invite）

const char* linphone_proxy_config_get_dial_prefix(const LinphoneProxyConfig* cfg)

      返回

            获取拨号前缀

const char* linphone_proxy_config_get_domain(const LinphoneProxyConfig* cfg)

      获取指定LinphoneProxyConfig对象的域的名字

      参数

               [in] cfg LinphoneProxyConfig对象

              返回

                                代理配置的域名

LinphoneReason linphone_proxy_config_get_error(const LinphoneProxyConfig* cfg)

      获取注册失败的原因，当代理配置状态为LinphoneRegistrationFailed时.

      参数

                [in] cfg LinphoneProxyConfig对象

            返回

                                 针对cfg注册识别的原因

const LinphoneErrorInfo* linphone_proxy_config_get_error_info(const LinphoneProxyConfig* cfg)

      获取注册失败的详细信息，当代理配置的状态为LinphoneRegistrationFailed时

      参数

                 [in] cfg LinphoneProxyConfig对象

      返回

                 注册失败的详细信息

int linphone_proxy_config_get_expire(const LinphoneProxyConfig* cfg)

     返回

                获取有效期

const char* linphone_proxy_config_get_file_transfer_server(const LinphoneProxyConfig* cfg)

     获取http文件传输服务器，被用于content type：application/vnd.gsma.rcs-ft-http+xml

     参数

              [in] cfg LinphoneProxyConfig对象

     返回

              文件服务器的URL，例如 https://file.linphone.org/upload.php

const char* linphone_proxy_config_get_identity(const LinphoneProxyConfig* cfg)

     已弃用：

             用linphone_proxy_config_get_identity_address()

const LinphoneAddress* linphone_proxy_config_get_identity_address（const LinphoneProxyConfig* cfg）

      返回

             属于这个代理配置的SIP身份

LinphoneNatPolicy* linphone_proxy_config_get_nat_policy(const LinphoneProxyConfig* cfg)

      获取在使用这个代理配置时所使用的穿透NAT/防火墙策略.如果参数被设置NULL，LinphoneCore默认的NAT策略会被用来代替.

      参数

               [in] cfg LinphoneProxyConfig对象

      返回

               LinphoneNatPolicy对象

      另外参见

               linphone_core_get_nat_policy()

LinphonePrivacyMask linphone_proxy_config_get_privacy(const LinponeProxyConfig* cfg)

      获取所有通话通过该代理路由的默认隐私策略

      参数

               [in] cfg LinphoneProxyConfig对象

      返回

                隐私模式

int linphone_proxy_config_get_publish_expires(const LinphoneProxyConfig* cfg)

      获取publish有效期,秒为单位.默认值是注册有效期

      参数

               [in]  cfg  LinphoneProxyConfig对象

      返回

                有效期 单位为秒

const char* linphone_proxy_config_get_quality_reporting_collector(const LinphoneProxyConfig* cfg)

    当使用质量报告时,获取收集器终端的路线.在丢包前,这个SIP地址应该被用在服务器上来处理数据包.收集器地址应该是一个不存在的用户，将不接收任何消息.如果为NULL，报告会被发送到代理域.

    参数

            [in] cfg LinphoneProxyConfig对象

    返回

            收集器终端的SIP地址

int linphone_proxy_config_get_quality_reporting_interval(LinphoneProxyConfig* cfg)

     获取区间报告的时间间隔，在使用质量报告时.

     参数

            [in] cfg LinphoneProxyConfig对象

     返回

            时间间隔 用秒为单位，0代表区间报告禁用

const char* linphone_proxy_config_get_realm(const LinphoneProxyConfig* cfg)

     获取指定代理配置的realm

     参数

            [in] cfg LinphoneProxyConfig对象

     返回

            代理配置的realm

const char* linphone_proxy_config_get_ref_key(const LinphoneProxyConfig* cfg)

     获取与该代理配置相关的持久的参考键，该参考键例如一个外部数据库的id.它存储在配置文件中，因此它可以在进程退出/重启中存活.

     参数

              [in] cfg LinphoneProxyConfig对象

     返回

               与cfg相关联的参考键字符串.如果没有相关联的参考键，则返回 NULL.

const char* linphone_proxy_config_get_route(const LinphoneProxyConfig* cfg)

      返回

            这个代理配置的路由设置

LinphoneRegistrationState linphone_proxy_config_get_state(const LinphoneProxyConfig* cfg)

      获取指定的代理配置的注册状态

      参数

              [in]  cfg LinphoneProxyConfig对象

      返回

              代理配置的注册状态

const char* linphone_proxy_config_get_transport(const LinphoneProxyConfig* cfg)

      从service rote,rote或addr中获取传输协议

      参数

               [in] LinphoneProxyConfig对象

      返回

               字符串传输协议（I.E udp,tcp,tls,dtls）

void* linphone_proxy_config_get_user_data(const LinphoneProxyConfig* cfg)

     获用与代理配置cfg相关联的户数据的指针

     参数

             [in]  cfg LinphoneProxyConfig对象

     返回

             与代理配置相关的用户数据指针

bool_t linphone_proxy_config_is_phone_number(LinphoneProxyConfig* proxy, const char* username)

     检查给定的输入是否为一个电话号码

     参数

             proxy  LinphoneProxyConfig参数,未使用，但可能包含有用的数据.可以为NULL.

             username  需要解析的字符串

     返回

            如果输入是一个手机号码返回TRUE,否则返回FALSE.

bool_t linphone_proxy_config_is_registered(const LinphoneProxyConfig* cfg)

      返回

             一个布尔值，表明用户是否成功注册到代理服务器上.

      已弃用：

               用linphone_proxy_config_get_state()代替

LinphoneProxyConfig* linphone_proxy_config_new(void )

      创建一个空的代理配置

     已弃用：

               用linphone_core_create_proxy_config代替

bool_t linphone_proxy_config_normalize_number(LinphoneProxyConfig* proxy, const char* userame, char* result, size_t result_len)

       参见 linphone_proxy_config_normalize_phone_number

      参数

              proxy    LinphoneProxyConfig对象包括国家代码或转义符号.如果为NULL，使用默认配置

              username 解析字符串

              result   新的标准化号码

              result   标准化号码 result的大小

      返回

             如果电话号码能被识别，返回TRUE，否则返回FALSE

      已弃用

              用 linphone_proxy_config_normalize_phone_number()代替

char* linphone_proxy_config_normalize_phone_number(LinphoneProxyConfig* proxy, const char* username)

   将一个人类可读电话号码标准化到一个基本的字符串.888-444-222变为88844422或者+33888444222 取决于LinphoneProxyConfig对象.如果输入一个电话号码，这个函数会生成一个规范化后的用户名.

    参数

             proxy  LinphoneProxyConfig对象 包含国家代码或者转义符号.如果为NULL,用来默认配置

            username 要解析的字符串

    返回

             如果输入是一个无效的电话号码，返回NULL，否则返回规范化后的电话号码

LinphoneAddress* linphone_proxy_config_normalize_sip_uri(LinphoneProxyConfig* proxy, const char* username)

    将一个人类可读的sip uri规范化为一个完全限定的LinphoneAddress.Sip地址应该看起来像<sip:usename@domain:port>.基本上这个函数执行以下任务

• 如果输入一个电话号码,预先考虑国家前缀，最后用“00”转换“+”.
• 如果没有提供domain部分,添加代理配置的域名.如果在这个时候没有提供代理，则返回NULL
• 如果没有现有的sip:,则预先考虑它.