PJSUA开发文档中文版.docx

《PJSUA开发文档中文版.docx》由会员分享，可在线阅读，更多相关《PJSUA开发文档中文版.docx（48页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、Pjsua 开发指南 关于 PJSIP：PJSIP 是一个小巧而性能优异的协议栈。请访问：http:/www.pjsip.org 获得更多信息。关于本文档：这是一份自由文档。每一个人都有权限按原样（verbatim copies）复制与分发此文档，但不允许修改。PJSUA API高级软电话的 API为构建 SIP UA 应用而设计的具有高水平的 API。模块PJSUA-API 的基本 API基本应用程序的创建、初始化、日志配置等。PJSUA-API 的信令传输管理 SIP 传输的 API。PJSUA-API 的账户管理PJSUA 帐户的管理。PJSUA-API 呼叫管理呼叫操作。PJSUA-A

2、PI 的好友、用户状态和即时消息好友管理，好友的状态和即时消息。PJSUA-API 的媒体操作媒体操作。详细说明一个为 C / C + +编程提供的 SIP 用户代理 APIPJSUA-API 是构建 SIP 多媒体用户代理应用而提供的非常高水平的 API。它把信令和媒体功能包装在一起放入一个易于使用的调用的 API 中，提供帐户管理，好友管理，状态，即时消息以及多媒体功能例如会议、文件流、本地回放、录音等。C/ C + +绑定应用程序必须与 PJSUA-lib 链接来使用这些 API。此外，该库依赖于以下库：pjsip-ua, pjsip-simple, pjsip-core, pjmedi

3、a,pjmedia-codec, pjlib-util,pjlib,应用程序还必须链接这些库。有关详细信息，请参阅入门Getting Started with PJSIP。pjsua_samples提供了一些例程： 例程：Simple PJSUA很简单的 SIP 用户代理，具有注册、打电话和媒体建立的功能，使用 PJSUA 的API，PJSUA 开发指南版权保留 可以无限分发 禁止修改！在 200 行代码内实现。PJSUA这是 PJSIP 协议和 PJMEDIA 的参考实现。 PJSUA 是基于控制台的应用程序，设计简单、易读，但功能强大，足以体现 PJSIP 和 PJMEDIA 提供的所有功

4、能。使用 PJSUA API关于如何创建和初始化 API 请参阅 PJSUA-API Basic API。PJSUA-API Basic APIPJSUA API - 高级软电话的 API基本的应用程序的创建、初始化，日志配置等。数据结构structpjsua_logging_configstructpjsua_mwi_infostructpjsua_reg_infostructpjsua_callbackstructpjsua_configstructpjsua_msg_datastructpj_stun_resolve_result定义#definePJSUA_INVALID_ID (-1

5、)#definePJSUA_DEFAULT_USE_SRTP PJMEDIA_SRTP_DISABLED#definePJSUA_DEFAULT_SRTP_SECURE_SIGNALING 1#definePJSUA_ADD_ICE_TAGS 1#definePJSUA_ACQUIRE_CALL_TIMEOUT 2000#definepjsip_cred_dup pjsip_cred_info_dupTypedefstypedef intpjsua_call_idtypedef intpjsua_acc_idtypedef intpjsua_buddy_idtypedef intpjsua_p

6、layer_idtypedef intpjsua_recorder_idtypedef intpjsua_conf_port_idtypedefvoid(*pj_stun_resolve_cb )(const pj_stun_resolve_result *result)枚举enumpjsua_create_media_transport_flag PJSUA_MED_TP_CLOSE_MEMBER = 1 enumpjsua_sip_timer_usePJSUA_SIP_TIMER_INACTIVE,PJSUA_SIP_TIMER_OPTIONAL,PJSUA_SIP_TIMER_REQUI

7、RED, PJSUA_SIP_TIMER_ALWAYS enumpjsua_100rel_usePJSUA_100REL_NOT_USED,PJSUA_100REL_MANDATORY, PJSUA_100REL_OPTIONAL enumpjsua_destroy_flagPJSUA_DESTROY_NO_RX_MSG=1,PJSUA_DESTROY_NO_TX_MSG = 2, PJSUA_DESTROY_NO_NETWORK 功能函数voidpjsua_logging_config_default (pjsua_logging_config *cfg)voidpjsua_logging_

8、config_dup (pj_pool_t *pool, pjsua_logging_config*dst, const pjsua_logging_config *src)voidpjsua_config_default (pjsua_config *cfg)voidpjsua_config_dup (pj_pool_t *pool, pjsua_config *dst, constpjsua_config *src)voidpjsua_msg_data_init (pjsua_msg_data *msg_data)pj_status_tpjsua_create (void)pj_statu

9、s_tpjsua_init (const pjsua_config *ua_cfg, const pjsua_logging_config*log_cfg, const pjsua_media_config *media_cfg)pj_status_tpjsua_start (void)pj_status_tpjsua_destroy (void)pj_status_tpjsua_destroy2 (unsigned flags)intpjsua_handle_events (unsigned msec_timeout)pj_pool_t *pjsua_pool_create (const c

10、har *name, pj_size_t init_size, pj_size_tincrement)pj_status_tpjsua_reconfigure_logging (const pjsua_logging_config *c)pjsip_endpoint*pjsua_get_pjsip_endpt (void)pjmedia_endpt*pjsua_get_pjmedia_endpt (void)pj_pool_factory*pjsua_get_pool_factory (void)pj_status_tpjsua_detect_nat_type (void)pj_status_

11、tpjsua_get_nat_type (pj_stun_nat_type *type)pj_status_tpjsua_resolve_stun_servers(unsignedcount,pj_str_tsrv,pj_bool_t wait, void *token, pj_stun_resolve_cb cb)pj_status_tpjsua_cancel_stun_resolution (void *token, pj_bool_t notify_cb)pj_status_tpjsua_verify_sip_url (const char *url)pj_status_tpjsua_v

12、erify_url (const char *url)pj_status_tpjsua_schedule_timer (pj_timer_entry *entry, const pj_time_val*delay)voidpjsua_cancel_timer (pj_timer_entry *entry)voidpjsua_perror (const char *sender, const char *title, pj_status_tstatus)voidpjsua_dump (pj_bool_t detail)详细说明基础的 PJSUA-API 控制PJSUA 的创作、初始化、启动，同时

13、还提供各种辅助功能。使用 PJSUA 库创建 PJSUA在任何事情之前，应用程序必须调用 pjsua_create（）创建 PJSUA。除其他事项外，这将初始化 PJLIB，PJLIB-util，并创建一个 SIP endpoint，在调用任何 PJLIB 功能之前这是至关重要的一步。这个函数被调用后，应用程序可以创建一个内存池（使用 pjsua_pool_create（），并从命令行或文件中读取配置，初始化 PJSUA 如下。初始化 PJSUA创建 PJSUA 后，应用程序可以通过调用 pjsua_init（）初始化 PJSUA。如果应用程序要设置它们，这个函数有几个参数可选。PJSUA-L

14、IB 初始化（C 语言）初始化 PJSUA 的示例（C 代码）： #include #define THIS_FILEFILE static pj_status_t app_init(void)pjsua_configua_cfg; pjsua_logging_config log_cfg; pjsua_media_configmedia_cfg;pj_status_t status;/ 再做任何事情之前必须创建 PJSUA! status = pjsua_create();if (status != PJ_SUCCESS) pjsua_perror(THIS_FILE, Error init

15、ializing pjsua, status); return status;/ 使用默认配置pjsua_config_default(&ua_cfg); pjsua_logging_config_default(&log_cfg); pjsua_media_config_default(&media_cfg);/ 应用程序若要被重写，则回调 pjsua_config: ua_cfg.cb.on_incoming_call = . ua_cfg.cb.on_call_state = ./ 自定义其他设置或用配置文件初始化它们./ 初始化 pjsuastatus = pjsua_init(&ua

16、_cfg, &log_cfg, &media_cfg); if (status != PJ_SUCCESS) pjsua_perror(THIS_FILE, Error initializing pjsua, status); return status;.其他初始化PJSUA 初始化后，应用程序将通常需要/想要执行下列任务：使用 pjsua_transport_create（）创建 SIP 传输。应用程序将为它支持每个传输类型（例如 UDP、TCP 和TLS）调用 pjsua_transport_create（）。更多信息，请参阅 PJSUA-API 的信令传输。使用 pjsua_acc_a

17、dd（）或 pjsua_acc_add_local（）创建一个或多个 SIP 帐号。SIP 帐户用于向 SIP 服务器注册。更多信息，请参阅 PJSUA-API 的帐务管理。使用 pjsua_buddy_add（）添加一个或多个好友。更多信息，请参阅 PJSUA-API的好友、用户状态和即时消息。选择配置声音设备，设置编解码器，设置其他媒体。更多信息，请参阅 PJSUA-API的媒体操作。运行 PJSUA完成初始化后，应用程序必须调用 pjsua_start（）开始 PJSUA。此功能将检查所有的设置是否正确配置，如果他们没有将采用默认设置，或者如果它是无法从丢失的设置中恢复则报告错误状态。大

18、多数设置都可以在运行时改变。例如，应用程序可以在运行时添加，修改，或删除帐户，好友，或改变媒体设置。开始 PJSUA 的例子 C 代码示例代码：static pj_status_t app_run(void)pj_status_t status;/ 运行 pjsuastatus = pjsua_start();if (status != PJ_SUCCESS) pjsua_destroy();pjsua_perror(THIS_FILE, Error starting pjsua, status); return status;/ 循环执行应用程序while (1) char choice10

19、;printf(Select menu: ); fgets(choice, sizeof(choice), stdin);.Define Documentation#define PJSUA_INVALID_ID (-1)无效 ID#define PJSUA_DEFAULT_USE_SRTP PJMEDIA_SRTP_DISABLED最多代理账户的数目，SRTP 模式下的默认值。有效值：PJMEDIA_SRTP_DISABLED，PJMEDIA_SRTP_OPTIONAL，and PJMEDIA_SRTP_MANDATORY. #define PJSUA_DEFAULT_SRTP_SECURE

20、_SIGNALING 1SRTP 安全信令要求的默认值。有效值为：0：SRTP 的不需要安全信号；1：SRTP需要安全传输如 TLS；2：SRTP 需要安全的终端到终端传输（SIPS）#define PJSUA_ADD_ICE_TAGS 1如果在配置中 ICE 使能，控制 PJSUA-LIB 是否应该添加 ICE 媒体功能的标签参数( ;+sip.ice ) 到联系首部，默认: 1#define PJSUA_ACQUIRE_CALL_TIMEOUT 2000在一次特定呼叫中获取互斥锁的超时值默认: 2000 ms#define pjsip_cred_dup pjsip_cred_info_du

21、p它的实现已经被转移至 sip_auth.hTypedef Documentation typedef int pjsua_call_id 呼叫标识typedef int pjsua_acc_id账户标识typedef int pjsua_buddy_id好友标识typedef int pjsua_player_id文件的播放器标识typedef int pjsua_recorder_id文件记录标识typedef int pjsua_conf_port_id会议端口标识typedef void(* pj_stun_resolve_cb)(const pj_stun_resolve_resul

22、t *result)定义的回调类型用于 pjsua_resolve_stun_servers().Enumeration Type Documentationenum pjsua_create_media_transport_flag 此枚举指定自定义媒体传输的选项Enumerator:PJSUA_MED_TP_CLOSE_MEMBER此 标 志 表 示 当pjmedia_transport_close()被调用时，媒体传输层必须关闭其“成员”或“子” 传输层。如果这个标志没有被指定，那么媒体传输层不能调用它的成员传输层的 pjmedia_transport_close()函数。enum pj

23、sua_sip_timer_use此枚举指定 SIP 会话计时器的使用Enumerator:PJSUA_SIP_TIMER_INACTIVE当此标志被指定时，除非在远程请求时被明确要求，会话计时器将不被用于任何会话。PJSUA_SIP_TIMER_OPTIONAL当此标志被指定时，当远程会话支持和使用时会话计时器时，它将被用于所有会话。PJSUA_SIP_TIMER_REQUIRED当此标志被指定时，建立远程会话必须支持会话计时器。PJSUA_SIP_TIMER_ALWAYS当此标志被指定时，会话计时器将被用于所有会话，无论远程会话支持/使用与否。enum pjsua_100rel_use这个

24、常数控制 100rel 扩展的使用Enumerator:PJSUA_100REL_NOT_USED不使用，对于 UAC，支持 100rel 将被显示在支持首部，这样其他人可以选择使用它；对于 UAS，即使 UAC 支持此功能，100rel 仍不会被使用。PJSUA_100REL_MANDATORY强制性。UAC 将 100rel 置于 Require 首部，UAS 拒绝支持首部不包含 100rel 的来电。PJSUA_100REL_OPTIONAL可选. 与 PJSUA_100REL_NOT_USED 相似，但对于 UAS,如果 UAC 支持此功能，100rel 将被使用。enum pjsua

25、_destroy_flag标志可用于 pjsua_destroy2() Enumerator:PJSUA_DESTROY_NO_RX_MSG允许发送传出的消息（如 unregistration, eventunpublication,BYEs, unsubscription 等），但不等待响应。 有时“尽力而为”是非常有用的。PJSUA_DESTROY_NO_TX_MSG不发送任何传出的消息。如果应用程序知道要发送消息的网络目前不佳时，这个标志是有用的。PJSUA_DESTROY_NO_NETWORK在摧毁过程中，不要发送或接收消息。这 个 标 志 速 记 为PJSUA_DESTROY_NO_

26、RX_MSG+PJSUA_DESTROY_NO_TX_MSG.Function Documentationvoid pjsua_logging_config_default(pjsua_logging_config *cfg)使用此函数来初始化日志配置Parameters:cfg 要初始化的日志配置void pjsua_logging_config_dup(pj_pool_t *pool,pjsua_logging_config *dst,const pjsua_logging_config *src)使用此函数来重新进行日志配置Parameters:pool使用的内存池dst目的配置src源

27、配置void pjsua_config_default(pjsua_config *cfg)使用此函数初始化 PJSUA 配置Parameters:cfg要初始化的 pjsua 配置void pjsua_config_dup(pj_pool_t *pjsua_config *const pjsua_config *)pool,dst, src重置 pjsua_config.Parameters:pool内存池dst目的配置src源配置void pjsua_msg_data_init(pjsua_msg_data *msg_data)初始化信息数据Parameters:msg_data要被初始化

28、的信息数据pj_status_t pjsua_create(void)实例化 PJSUA 应用。应用程序调用任何其他功能之前必须调用这个函数，以确保正确初始化底层库。一旦这个函数返回成功，在退出应用程序之前，必须调用pjsua_destroy（）。Returns: PJ_SUCCESS（成功），或相应的错误代码。pj_status_t pjsua_init(const pjsua_config *ua_cfg,const pjsua_logging_config *log_cfg,const pjsua_media_config *media_cfg)初始化 PJSUA 指定的设置。所有的设置

29、是可选的，当配置未指定时，将使用默认值请注意，调用此函数之前必须调用 pjsua_create（） Parameters:ua_cfg用户代理配置log_cfg可选的日志设置media_cfg可选的媒体配置Returns:PJ_SUCCESS（成功），或相应的错误代码。pj_status_t pjsua_start(void)应用建议所有初始化完成后调用此函数，使库可以做额外的创建检查应用调用 pjsua_init（）后可随时使用这个函数。Returns:PJ_SUCCESS（成功），或相应的错误代码。pj_status_t pjsua_destroy(void)摧毁 PJSUA。应用建议执行

30、正常关闭（如注销 SIP 服务器的帐户，终止在线状态， 结束回话）后调用这个函数，当然，如果发现需要被终止活动的会话，这个函数将做所有这些。此函数将滞后一秒钟，等待来自远程的答复如果不保持跟踪它的状态，应用程序可以安全地多次调用这个函数另见:pjsua_destroy2() Returns:PJ_SUCCESS（成功），或相应的错误代码。pj_status_t pjsua_destroy2(unsignedflags)使用其他标志灵活摧毁 PJSUA Parameters:flags枚举型 pjsua_destroy_flag 的组合Returns:PJ_SUCCESS（成功），或相应的错误代

31、码。int pjsua_handle_events(unsignedmsec_timeout)轮询 PJSUA 的事件，如果必要块的调用者线程可指定最大时间间隔（以毫秒为单位）应用通常不需要调用这个函数，如果在 pjsua_config 结构中，它已经配置了工作线程（thread_cnt field），因为轮询将由这些工作线程完成Parameters:msec_timeout等待的最长时间，以毫秒为单位Returns:在轮询中已处理事件的数量。负值表示错误，应用程序可以检索错误(status =-return_value)pj_pool_t* pjsua_pool_create(const c

32、har *pj_size_t pj_size_t)name,init_size, increment创建应用程序使用的内存池。一旦应用程序使用完池，它必须用 pj_pool_release（）释放Parameters:name可选池名称init_size初始化内存池大小. increment增量的大小Returns:内存池，或当没有内存时返回 NULLpj_status_t pjsua_reconfigure_logging(const pjsua_logging_config *c)应用程序可以在任何时间（当然在 pjsua_create（）之后）调用此功能更改日志设置Parameters:

33、c记录配置Returns:PJ_SUCCESS（成功），或相应的错误代码。pjsip_endpoint* pjsua_get_pjsip_endpt(void)内部函数来获取 PJSUA 的 SIP endpoint 实例，有时这是必须的例如登记模块，创建传输等，其只有 pjsua_init（）后调用有效Returns:SIP endpoint 实例pjmedia_endpt* pjsua_get_pjmedia_endpt(void)内部函数来获取 media endpoint 实例，其只有 pjsua_init()后调用有效Returns:Media endpoint 实例pj_pool_

34、factory* pjsua_get_pool_factory(void)内部函数来获取 PJSUA 内存池工厂，其只有在 pjsua_create() 后调用有效Returns:PJSUA 目前使用的内存池pj_status_t pjsua_detect_nat_type(void)函数在 endpoint 前面检测 NAT 类型。一旦成功调用，这个函数将异步执行并报告 pjsua_callback 回调的 on_nat_detect（）中的结果在 NAT 检测后执行回调，应用程序可以通过调用 pjsua_get_nat_type（）检测 NAT 类型。应用程序也可以在稍后时间再次通过调用

35、pjsua_detect_nat_type（）执行NAT 检测请注意，STUN 必须启用来成功地运行此函数。Returns:PJ_SUCCESS（成功），或相应的错误代码。pj_status_t pjsua_get_nat_type(pj_stun_nat_type *type)与 pjsua_detect_nat_type() 函 数 相 似 得 到 NAT 类 型 。 这 个 函 数 在pjsua_detect_nat_type()成功执行和 on_nat_detect()回调后，仅返回有用的 NAT 类型Parameters:typeNAT 类型Returns:在 检 测 过 程 中 ，

36、 函 数 将 返 回 PJ_EPENDING ， 类 型 将 被 设 置 为PJ_STUN_NAT_TYPE_UNKNOWN。在NAT 类型成功检测后，函数将返回PJ_SUCCESS ， 类 型 将 被 置 于 正 确 值 。 其 他 返 回 值 表 示 错 误 ， 类 型 将 被 置 于PJ_STUN_NAT_TYPE_ERR_UNKNOWN另见: pjsua_call_get_rem_nat_type()pj_status_t pjsua_resolve_stun_servers(unsignedcount,pj_str_tsrv,pj_bool_twait,void *token,pj_

37、stun_resolve_cbcb)辅助功能，以解决和联系每个 STUN 服务器项目（按顺序），找出哪些是可用的。调用此函数之前必须已调用 pjsua_init（） Parameters:countSTUN 服务器项目的数量srvSTUN 服务器项目的列表。请参阅在 pjsua_config 文档中关于项目格式的 stun_srv 部分wait指定非零阻碍改函数，直到它得到的结果。在这种情况下，当正在做决议时该函数将被阻止，这个函数返回之前回调将被调用。token在回调中任意令牌将被传回应用程序cb回调将被调用来通知函数结果Returns:等待参数非零时，如果一个可用的 STUN 服务器被发现

38、将返回 PJ_SUCCESS。否则它将始终返回 PJ_SUCCESS，应用程序将在回调中通知结果pj_status_t pjsua_cancel_stun_resolution(void *pj_bool_ttoken,notify_cb)取消挂起的符合指定令牌的 STUN 决议Parameters:token匹配的令牌. 令牌将用于 pjsua_resolve_stun_servers()notify_cb布尔型来控制回调是否应该为取消的决议调用，当回调被调用时， 结果的状态将被设为 PJ_ECANCELLEDReturns:如果有至少有一个悬而未决的 STUN 决议被取消返回 PJ_SUC

39、CESS如果有没有匹配的或其他错误返回 PJ_ENOTFOUNDpj_status_t pjsua_verify_sip_url(const char *url)函数来验证 SIP URL 的有效性。如果 URL 是个有效的 SIP/SIPS,将返回 PJ_SUCCESS Parameters:urlURL（以 NULL 结尾的字符串） Returns: PJ_SUCCESS（成功），或相应的错误代码另见:pjsua_verify_url()pj_status_t pjsua_verify_url(const char *url)函数来验证 URL 的有效性。与 pjsua_verify_si

40、p_url()不同，如果使用了 tel:URL,则返回 PJ_SUCCESSParameters:urlURL（以 NULL 结尾的字符串） Returns: PJ_SUCCESS（成功），或相应的错误代码 另见:pjsua_verify_sip_url()pj_status_t pjsua_schedule_timer(pj_timer_entry *entry,const pj_time_val *delay)启动一个定时器。请注意，定时器的回调可能由不同的线程来执行，这取决于是否启用工作线程Parameters:entry定时器实体delay时间间隔Returns: PJ_SUCCESS

41、（成功），或相应的错误代码另见:pjsip_endpt_schedule_timer()void pjsua_cancel_timer(pj_timer_entry *entry)删除先前的定时器Parameters:entry定时器实体另见:pjsip_endpt_cancel_timer()void pjsua_perror( const char * const char * pj_status_t)sender, title, status函数现实错误代码对应的错误信息。错误信息将被发送到日志中Parameters:sender 发送者字段title错误消息的标题. status状态码

42、void pjsua_dump(pj_bool_tdetail)把堆栈状态转储到日志，使用 verbosity level 3 Parameters:detail当非零时，将打印出详细的输出(如 SIP 通信列表)PJSUA-API Signaling TransportPJSUA API - 高级软电话的 API管理 SIP 传输的 API数据结构structpjsua_transport_configstructpjsua_transport_infoTypedefstypedef intpjsua_transport_id函数voidpjsua_transport_config_defa

43、ult (pjsua_transport_config *cfg)voidpjsua_transport_config_dup (pj_pool_t *pool, pjsua_transport_config*dst, const pjsua_transport_config *src)pj_status_tpjsua_transport_create(pjsip_transport_type_etype,constPjsua 开发指南 侯凯 http:/www.pjsip.org/pjsip/docs/html/group PJSUA LIB.htmpjsua_transport_confi

44、g *cfg, pjsua_transport_id *p_id)pj_status_tpjsua_transport_register(pjsip_transport*tp,pjsua_transport_id*p_id)pj_status_tpjsua_enum_transports (pjsua_transport_id id, unsigned *count)pj_status_tpjsua_transport_get_info (pjsua_transport_id id, pjsua_transport_info*info)pj_status_tpjsua_transport_set_enable(pjsua_transport_idid,pj_bool_tenabled)pj_status_tpjsua_transport_close (pjsua_transport_id id, pj_bool_t force)详细说明PJSUA-API 支持创建多个传输实例，例如 UDP，TCP 和 TLS。在添加账户之前必须创建 SIP 传输Typedef Documentationtypedefintpjsua_transp