PJSUA-API Basic API

 

PJSUA-API Basic API
[PJSUA API - High Level Softphone API]

Basic application creation/initialization, logging configuration, etc. More... 基本应用的创建/初始化，日志的配置等等

Data Structures 数据结构

struct  pjsua_logging_config struct  pjsua_mwi_infostruct  pjsua_callbackstruct  pjsua_configstruct  pjsua_msg_datastruct  pj_stun_resolve_result

Defines  预定义

#define PJSUA_INVALID_ID   (-1)#define PJSUA_DEFAULT_USE_SRTP   PJMEDIA_SRTP_DISABLED#define PJSUA_DEFAULT_SRTP_SECURE_SIGNALING   1#define PJSUA_ADD_ICE_TAGS   1#define PJSUA_ACQUIRE_CALL_TIMEOUT   2000#define pjsip_cred_dup   pjsip_cred_info_dup

Typedefs 定义

typedef int pjsua_call_idtypedef int pjsua_acc_idtypedef int pjsua_buddy_idtypedef int pjsua_player_idtypedef int pjsua_recorder_idtypedef int pjsua_conf_port_idtypedef void(* pj_stun_resolve_cb )(const pj_stun_resolve_result *result)

Enumerations 枚举

enum  pjsua_sip_timer_use { PJSUA_SIP_TIMER_INACTIVE, PJSUA_SIP_TIMER_OPTIONAL, PJSUA_SIP_TIMER_REQUIRED, PJSUA_SIP_TIMER_ALWAYS }

Functions 函数

void pjsua_logging_config_default (pjsua_logging_config *cfg)void pjsua_logging_config_dup (pj_pool_t *pool, pjsua_logging_config *dst, const pjsua_logging_config *src)void pjsua_config_default (pjsua_config *cfg)void pjsua_config_dup (pj_pool_t *pool, pjsua_config *dst, const pjsua_config *src)void pjsua_msg_data_init (pjsua_msg_data *msg_data)pj_status_t pjsua_create (void)pj_status_t pjsua_init (const pjsua_config *ua_cfg, const pjsua_logging_config *log_cfg, const pjsua_media_config *media_cfg)pj_status_t pjsua_start (void)pj_status_t pjsua_destroy (void)int pjsua_handle_events (unsigned msec_timeout)pj_pool_t * pjsua_pool_create (const char *name, pj_size_t init_size, pj_size_t increment)pj_status_t pjsua_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_t pjsua_detect_nat_type (void)pj_status_t pjsua_get_nat_type (pj_stun_nat_type *type)pj_status_t pjsua_resolve_stun_servers (unsigned count, pj_str_t srv[], pj_bool_t wait, void *token, pj_stun_resolve_cb cb)pj_status_t pjsua_cancel_stun_resolution (void *token, pj_bool_t notify_cb)pj_status_t pjsua_verify_sip_url (const char *url)pj_status_t pjsua_schedule_timer (pj_timer_entry *entry, const pj_time_val *delay)void pjsua_cancel_timer (pj_timer_entry *entry)void pjsua_perror (const char *sender, const char *title, pj_status_t status)void pjsua_dump (pj_bool_t detail)

---

Detailed Description 详细信息

The base PJSUA API controls PJSUA creation, initialization, and startup, and also provides various auxiliary functions.

基础PJSUA的API控制PJSUA的创建，初始化，启动以及提供各种的辅助函数

Using PJSUA Library

Creating PJSUA 创建PJSUA

Before anything else, application must create PJSUA by calling pjsua_create(). This, among other things, will initialize PJLIB, which is crucial before any PJLIB functions can be called, PJLIB-UTIL, and create a SIP endpoint.

After this function is called, application can create a memory pool (with pjsua_pool_create()) and read configurations from command line or file to build the settings to initialize PJSUA below.

在使用任何东西之前，应用程序首先必须使用pjsua_create()来创建PJSUA，创建过程同时完成了PJLIB的初始化（调用PJLIB函数之前关键的一步）和PJLIB—UTIL的初始化以及SIP ednpoint的创建

Initializing PJSUA 初始化PJSUA

After PJSUA is created, application can initialize PJSUA by calling pjsua_init(). This function takes several optional configuration settings in the argument, if application wants to set them.

在PJSUA创建之后，应用程序可以通过调用pjsua_init()来初始化PJSUA，该函数允许你自定义多个配置选项来完成PJSUA的初始化，例如日志配置，媒体编码配置，帐户配置，回调函数等等

PJSUA-LIB Initialization (in C)

Sample code to initialize PJSUA in C code:   

 #include <pjsua-lib/pjsua.h> #define THIS_FILE  __FILE__ static pj_status_t app_init(void) {    pjsua_config         ua_cfg;    pjsua_logging_config log_cfg;    pjsua_media_config   media_cfg;    pj_status_t status;    // Must create pjsua before anything else!，首先必须做的是创建PJSUA    status = pjsua_create();    if (status != PJ_SUCCESS) {        pjsua_perror(THIS_FILE, "Error initializing pjsua", status);        return status;    }    // Initialize configs with default settings.    用默认设置初始化配置    pjsua_config_default(&ua_cfg);    pjsua_logging_config_default(&log_cfg);    pjsua_media_config_default(&media_cfg);    // At the very least, application would want to override  自定义配置中的变量以及参数等    // the call callbacks in pjsua_config:         例如配置回调函数    ua_cfg.cb.on_incoming_call = ...    ua_cfg.cb.on_call_state = ..    ...    // Customize other settings (or initialize them from application specific    // configuration file): 自定义其它配置或者从特定的配置文件中读取配置进行初始化    ...     // Initialize pjsua   使用预先定义的各种配置来初始化PJSUA    status = pjsua_init(&ua_cfg, &log_cfg, &media_cfg);    if (status != PJ_SUCCESS) {          pjsua_perror(THIS_FILE, "Error initializing pjsua", status);          return status;    }    .    ... }

Other Initialization 其他初始化

After PJSUA is initialized with pjsua_init(), application will normally need/want to perform the following tasks:

初始化PJSUA之后，程序通常还需要执行以下任务：

• create SIP transport with pjsua_transport_create(). Application would to call pjsua_transport_create() for each transport types that it wants to support (for example, UDP, TCP, and TLS). Please see PJSUA-API Signaling Transport section for more info.
• 创建sip的传输模式，例如UDP，TCP，TLS，更多信息参考 PJSUA-API Signaling Transport（PJSUA信令传送模式）
• create one or more SIP accounts with pjsua_acc_add() or pjsua_acc_add_local(). The SIP account is used for registering with the SIP server, if any. Please see PJSUA-API Accounts Management for more info.
• 创建一个或多个SIP帐户用来注册到SIP服务器，更多信息参考PJSUA帐户管理api
• add one or more buddies with pjsua_buddy_add(). Please see PJSUA-API Buddy, Presence, and Instant Messaging section for more info.
• 添加一个或多个联系人，用于订阅获取联系人状态，以便发送IM消息
• optionally configure the sound device, codec settings, and other media settings. Please see PJSUA-API Media Manipulation for more info.
• 可选配置还包括，声音设备，编码设置，以及其他媒体设置等，参考PJSUA的媒体api

Starting PJSUA 启动PJSUA

After all initializations have been done, application must call pjsua_start() to start PJSUA. This function will check that all settings have been properly configured, and apply default settings when they haven't, or report error status when it is unable to recover from missing settings.

Most settings can be changed during run-time. For example, application may add, modify, or delete accounts, buddies, or change media settings during run-time.

初始化完成后，应用程序就必须通过调用pjsua_start()函数来启动PJSUA，该函数检查所有前面正确配置过的设置，如果没有设置则会使用默认设置，或者如果无法覆盖丢失的设置则会输出错误状态

大多数设置在运行过程中会修改，例如应用程序可能添加，修改，删除帐号，联系人或者修改媒体设置等

C Example for Starting PJSUA

Sample code:

 static pj_status_t app_run(void) {    pj_status_t status;    // Start pjsua    status = pjsua_start();    if (status != PJ_SUCCESS) {        pjsua_destroy();        pjsua_perror(THIS_FILE, "Error starting pjsua", status);        return status;    }    // Run application loop    while (1) {        char choice[10];                printf("Select menu: ");        fgets(choice, sizeof(choice), stdin);        ...    } }

---

Define Documentation 预定义文档

#define PJSUA_INVALID_ID   (-1)

Constant to identify invalid ID for all sorts of IDs.

定义验证各种无效ID的常数

#define PJSUA_DEFAULT_USE_SRTP   PJMEDIA_SRTP_DISABLED

Maximum proxies in account. Default value of SRTP mode usage. Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and PJMEDIA_SRTP_MANDATORY.

默认使用SRTP的模式

#define PJSUA_DEFAULT_SRTP_SECURE_SIGNALING   1

Default value of secure signaling requirement for SRTP. Valid values are: 0: SRTP does not require secure signaling 1: SRTP requires secure transport such as TLS 2: SRTP requires secure end-to-end transport (SIPS)

使用SRTP的默认加密信令方式，0是SRTP不需要加密信令，1是SRTP需要加密传输例如TLS，2是SRTP需要加密端到端的传输模式（sips）

#define PJSUA_ADD_ICE_TAGS   1

Controls whether PJSUA-LIB should add ICE media feature tag parameter (the ";+sip.ice" parameter) to Contact header if ICE is enabled in the config.

Default: 1

#define PJSUA_ACQUIRE_CALL_TIMEOUT   2000

Timeout value used to acquire mutex lock on a particular call.

Default: 2000 ms

#define pjsip_cred_dup   pjsip_cred_info_dup

The implementation has been moved to sip_auth.h

---

Typedef Documentation

typedef int pjsua_call_id

Call identification

typedef int pjsua_acc_id

Account identification

typedef int pjsua_buddy_id

Buddy identification

typedef int pjsua_player_id

File player identification

typedef int pjsua_recorder_id

File recorder identification

typedef int pjsua_conf_port_id

Conference port identification

typedef void(* pj_stun_resolve_cb)(const pj_stun_resolve_result *result)

Typedef of callback to be registered to pjsua_resolve_stun_servers().

---

Enumeration Type Documentation

enum pjsua_sip_timer_use

This enumeration specifies the usage of SIP Session Timers extension. 该每句类型定义了SIP会话定时器扩展的使用

Enumerator:

PJSUA_SIP_TIMER_INACTIVE 

When this flag is specified, Session Timers will not be used in any session, except it is explicitly required in the remote request.

定义INACTIVE时，会话定时器将不会使用在任何会话中，除非远端请求明确指出需要定时器

PJSUA_SIP_TIMER_OPTIONAL 

When this flag is specified, Session Timers will be used in all sessions whenever remote supports and uses it.

当远端支持和使用会话定时器时，定时器将存在于会话中

PJSUA_SIP_TIMER_REQUIRED 

When this flag is specified, Session Timers support will be a requirement for the remote to be able to establish a session.

要求远端必须支持会话定时器来建立会话

PJSUA_SIP_TIMER_ALWAYS 

When this flag is specified, Session Timers will always be used in all sessions, regardless whether remote supports/uses it or not.

会话定时器始终存在与所有会话，不管远端是否支持和使用它

---

Function Documentation 函数文档

void pjsua_logging_config_default(pjsua_logging_config * cfg )  

Use this function to initialize logging config.

该函数用于初始化日志参数配置

Parameters:

 cfg The logging config to be initialized.

void pjsua_logging_config_dup(pj_pool_t * pool,  pjsua_logging_config * dst,  const pjsua_logging_config * src  )   

Use this function to duplicate logging config.

该函数用于复制日志配置

Parameters:

 pool Pool to use.//使用的内存池 dst Destination config.//目的配置 src Source config. //源配置

void pjsua_config_default(pjsua_config * cfg )  

Use this function to initialize pjsua config.

该函数用于初始化PJSUA的配置

Parameters:

 cfg pjsua config to be initialized.

void pjsua_config_dup(pj_pool_t * pool,  pjsua_config * dst,  const pjsua_config * src  )   

Duplicate pjsua_config.

Parameters:

 pool The pool to get memory from. dst Destination config. src Source config.

void pjsua_msg_data_init(pjsua_msg_data * msg_data )  

Initialize message data. 初始化消息数据

Parameters:

 msg_data Message data to be initialized.

pj_status_t pjsua_create(void   )  

Instantiate pjsua application. Application must call this function before calling any other functions, to make sure that the underlying libraries are properly initialized. Once this function has returned success, application must call pjsua_destroy() before quitting.

实例化PJSUA应用，该函数必须首先在应用程序中调用，用以确认底层库正确初始化，一旦该函数返回success，那么应用程序在退出前必须调用pjsua_destroy()来销毁

Returns:

PJ_SUCCESS on success, or the appropriate error code. 返回PJ_SUCCESS或者相应的错误代码

pj_status_t pjsua_init(const pjsua_config * ua_cfg,  const pjsua_logging_config * log_cfg,  const pjsua_media_config * media_cfg  )   

Initialize pjsua with the specified settings. All the settings are optional, and the default values will be used when the config is not specified.

Note that pjsua_create() MUST be called before calling this function.

用自定义的配置初始化PJSUA，所有的配置都是可选的，如果没有对应设置则使用默认值

注意： pjsua_create() 必须在这之前调用

Parameters:

 ua_cfg User agent configuration. log_cfg Optional logging configuration. media_cfg Optional media configuration.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_start(void   )  

Application is recommended to call this function after all initialization is done, so that the library can do additional checking set up additional

Application may call this function anytime after pjsua_init().

必须在初始化完成之后调用该函数，以便可以额外检查附加设置。

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_destroy(void   )  

Destroy pjsua. Application is recommended to perform graceful shutdown before calling this function (such as unregister the account from the SIP server, terminate presense subscription, and hangup active calls), however, this function will do all of these if it finds there are active sessions that need to be terminated. This function will approximately block for one second to wait for replies from remote.

Application.may safely call this function more than once if it doesn't keep track of it's state.

销毁pjsua，在应用程序执行正常关闭前需要调用该函数（例如从sip server上注销帐户，中断消息订阅，挂掉通话等等），如果函数注销时发现有正在通话的会话需要终止，函数会锁定1秒钟等待远端消息反馈

Returns:

PJ_SUCCESS on success, or the appropriate error code.

int pjsua_handle_events(unsigned msec_timeout )  

Poll pjsua for events, and if necessary block the caller thread for the specified maximum interval (in miliseconds).

Application doesn't normally need to call this function if it has configured worker thread (thread_cnt field) in pjsua_config structure, because polling then will be done by these worker threads instead.

PJSUA事件轮询，如果需要，则以最大的特定间隔锁定调用线程（毫秒级）。如果已经配置工作线程(pjsua_config结构体中的thread_cnt field) ，应用程序通常不是需要调用该函数

 

Parameters:

 msec_timeout Maximum time to wait, in miliseconds.

Returns:

The number of events that have been handled during the poll. Negative value indicates error, and application can retrieve the error as (status = -return_value).

返回轮询时被处理的事件数量，负值便是错误，应用程序可以检查到错误的

pj_pool_t* pjsua_pool_create(const char * name,  pj_size_t init_size,  pj_size_t increment  )   

Create memory pool to be used by the application. Once application finished using the pool, it must be released with pj_pool_release().

创建应用程序使用的内存池，一旦应用程序完成使用该内存池，必须使用 pj_pool_release().来释放

Parameters:

 name Optional pool name. init_size Initial size of the pool. increment Increment size.

Returns:

The pool, or NULL when there's no memory.

返回内存池地址，或者当没有内存可用返回NULL

pj_status_t pjsua_reconfigure_logging(const pjsua_logging_config * c )  

Application can call this function at any time (after pjsua_create(), of course) to change logging settings.

应用程序可以在任何时间调用该函数（当然要在pjsua_create()之后了），来修改日志配置

Parameters:

 c Logging configuration.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pjsip_endpoint* pjsua_get_pjsip_endpt(void   )  

Internal function to get SIP endpoint instance of pjsua, which is needed for example to register module, create transports, etc. Only valid after pjsua_init() is called.

内部函数用于获得pjsua的sip endpoint实例，在例如注册模块，创建传输模式等时候需要，必须在有效调用pjsua_init()初始化之后调用

Returns:

SIP endpoint instance.

pjmedia_endpt* pjsua_get_pjmedia_endpt(void   )  

Internal function to get media endpoint instance. Only valid after pjsua_init() is called.

内部函数用于获取media endpoint 实例，必须在pjsua_init()初始化之后调用

Returns:

Media endpoint instance.

pj_pool_factory* pjsua_get_pool_factory(void   )  

Internal function to get PJSUA pool factory. Only valid after pjsua_create() is called.

内部函数获取PJSUA 出厂池地址，必须在有效调用pjsua_create()之后调用

Returns:

Pool factory currently used by PJSUA.

pj_status_t pjsua_detect_nat_type(void   )  

This is a utility function to detect NAT type in front of this endpoint. Once invoked successfully, this function will complete asynchronously and report the result in on_nat_detect()callback of pjsua_callback.

After NAT has been detected and the callback is called, application can get the detected NAT type by calling pjsua_get_nat_type(). Application can also perform NAT detection by calling pjsua_detect_nat_type() again at later time.

Note that STUN must be enabled to run this function successfully.

sip endpoint前台检测NAT类型的工具函数，成功引用后，函数将完成异步调用，并且在回调函数on_nat_detect()中调用输出结果

NAT被检测之后，回调函数被调用，应用程序可以通过调用Pjsua_get_nat_type()获得NAT的检测结果，应用程序可以在后面再次执行NAT检测的调用

注意：STUN必须启用才能成功调用该函数

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_get_nat_type(pj_stun_nat_type * type )  

Get the NAT type as detected by pjsua_detect_nat_type() function. This function will only return useful NAT type after pjsua_detect_nat_type() has completed successfully andon_nat_detect() callback has been called.

获得NAT类型，通过上面的检测函数，返回常用NAT类型，

Parameters:

 type NAT type.

Returns:

When detection is in progress, this function will return PJ_EPENDING and type will be set to PJ_STUN_NAT_TYPE_UNKNOWN. After NAT type has been detected successfully, this function will return PJ_SUCCESS and type will be set to the correct value. Other return values indicate error and type will be set to PJ_STUN_NAT_TYPE_ERR_UNKNOWN.

函数开始执行检测开始返回PJ_EPENDING并且类型设置为PJ_STUN_NAT_TYPE_UNKNOWN，当NAT类型成功检测完成后，函数将返回PJ_SUCCESS并且类型被赋值正确的类型，如果错误将返回PJ_STUN_NAT_TYPE_ERR_UNKNOWN

See also:

pjsua_call_get_rem_nat_type()

pj_status_t pjsua_resolve_stun_servers(unsigned count,  pj_str_t srv[],  pj_bool_t wait,  void * token,  pj_stun_resolve_cb cb  )   

Auxiliary function to resolve and contact each of the STUN server entries (sequentially) to find which is usable. The pjsua_init() must have been called before calling this function.

辅助函数用于解析并联系每个STUN服务器入口（顺序），从而找到哪个服务器不可用

Parameters:

 count Number of STUN server entries to try. 需要尝试解析的STUN服务器入口数量 srv 

Array of STUN server entries to try. Please see the stun_srv field in the pjsua_config documentation about the format of this entry.

STUN服务器入口的数组，参考pjsua_config文档的stun_srv字段获得更多关于该数组的格式

 wait 

Specify non-zero to make the function block until it gets the result. In this case, the function will block while the resolution is being done, and the callback will be called before this function returns.

定义非零从而让函数锁定，直到获得返回结果，本例中，函数将锁定直到解析完成，同时回调函数将在函数返回之前调用

 token Arbitrary token to be passed back to application in the callback.回调过程中传递给应用程序的令牌 cb Callback to be called to notify the result of the function. 函数消息结果通知所调用的回调函数

Returns:

If wait parameter is non-zero, this will return PJ_SUCCESS if one usable STUN server is found. Otherwise it will always return PJ_SUCCESS, and application will be notified about the result in the callback.

等待非零参数事件后，只要有一个STUN 服务器找到则返回PJ_SUCCESS。

pj_status_t pjsua_cancel_stun_resolution(void * token,  pj_bool_t notify_cb  )   

Cancel pending STUN resolution which match the specified token.

有特定令牌匹配则取消STUN解析的等待

Parameters:

 token The token to match. This token was given to pjsua_resolve_stun_servers() notify_cb Boolean to control whether the callback should be called for cancelled resolutions. When the callback is called, the status in the result will be set as PJ_ECANCELLED.

Returns:

PJ_SUCCESS if there is at least one pending STUN resolution cancelled, or PJ_ENOTFOUND if there is no matching one, or other error.

pj_status_t pjsua_verify_sip_url(const char * url )  

This is a utility function to verify that valid SIP url is given. If the URL is valid, PJ_SUCCESS will be returned.

验证SIP url有效性的工具函数，如果有效则返回PJ_SUCCESS

Parameters:

 url The URL, as NULL terminated string.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_schedule_timer(pj_timer_entry * entry,  const pj_time_val * delay  )   

Schedule a timer entry. Note that the timer callback may be executed by different thread, depending on whether worker thread is enabled or not.

进度/计划定时器，注意定时器回调可能在不同的线程被调用，这取决于工作线程是否启用

Parameters:

 entry Timer heap entry. delay The interval to expire.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

See also:

pjsip_endpt_schedule_timer()

void pjsua_cancel_timer(pj_timer_entry * entry )  

Cancel the previously scheduled timer.

取消前面的进度/计划定时器

Parameters:

 entry Timer heap entry.

See also:

pjsip_endpt_cancel_timer()

void pjsua_perror(const char * sender,  const char * title,  pj_status_t status  )   

This is a utility function to display error message for the specified error code. The error message will be sent to the log.

错误消息输出

Parameters:

 sender The log sender field. title Message title for the error. status Status code.

void pjsua_dump(pj_bool_t detail )  

This is a utility function to dump the stack states to log, using verbosity level 3.

状态日志输出

Parameters:

 detail Will print detailed output (such as list of SIP transactions) when non-zero.