PJSUA-API Basic API

Basic application creation/initialization, logging configuration, etc. More...

Data Structures
struct	pjsua_logging_config
struct	pjsua_mwi_info
struct	pjsua_reg_info
struct	pjsua_stream_info
struct	pjsua_stream_stat
struct	pjsua_on_stream_precreate_param
struct	pjsua_on_stream_created_param
struct	pjsua_med_tp_state_info
struct	pjsua_srtp_opt
union	pjsua_ip_change_op_info
struct	pjsua_dtmf_info
struct	pjsua_dtmf_event
struct	pjsua_call_setting
struct	pjsua_callback
struct	pjsua_config
struct	pjsua_msg_data
struct	pj_stun_resolve_result
struct	pjsua_ip_change_param
struct	pjsua_ip_change_acc_cfg

Macros
#define	DISABLED_FOR_TICKET_1185   0
#define	PJSUA_POOL_LEN   1000
#define	PJSUA_POOL_INC   1000
#define	PJSUA_POOL_LEN_ACC   512
#define	PJSUA_POOL_INC_ACC   256
#define	PJSUA_ACC_MAX_PROXIES   8
#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	PJSUA_HAS_VIDEO   PJMEDIA_HAS_VIDEO
#define	PJSUA_VID_REQ_KEYFRAME_INTERVAL   3000
#define	PJSUA_SEPARATE_WORKER_FOR_TIMER   0
#define	PJSUA_DISABLE_AUTO_SEND_100   0
#define	PJSUA_ICE_TRANSPORT_OPTION   0
#define	PJSUA_TRICKLE_ICE_NEW_CAND_CHECK_INTERVAL   100
#define	PJSUA_UNKNOWN_DTMF_DURATION   ((unsigned)-1)
#define	pjsip_cred_dup   pjsip_cred_info_dup

Typedefs
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 pj_status_t(*	pjsua_med_tp_state_cb) (pjsua_call_id call_id, const pjsua_med_tp_state_info *info)
typedef void(*	pj_stun_resolve_cb) (const pj_stun_resolve_result *result)

Enumerations
enum	pjsua_invalid_id_const_ { PJSUA_INVALID_ID = -1 }
enum	pjsua_state {   PJSUA_STATE_NULL , PJSUA_STATE_CREATED , PJSUA_STATE_INIT , PJSUA_STATE_STARTING ,   PJSUA_STATE_RUNNING , PJSUA_STATE_CLOSING }
enum	pjsua_med_tp_st {   PJSUA_MED_TP_NULL , PJSUA_MED_TP_CREATING , PJSUA_MED_TP_IDLE , PJSUA_MED_TP_INIT ,   PJSUA_MED_TP_RUNNING , PJSUA_MED_TP_DISABLED }
enum	pjsua_create_media_transport_flag { PJSUA_MED_TP_CLOSE_MEMBER = 1 }
enum	pjsua_contact_rewrite_method { PJSUA_CONTACT_REWRITE_UNREGISTER = 1 , PJSUA_CONTACT_REWRITE_NO_UNREG = 2 , PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE = 4 }
enum	pjsua_ip_change_op {   PJSUA_IP_CHANGE_OP_NULL , PJSUA_IP_CHANGE_OP_RESTART_LIS , PJSUA_IP_CHANGE_OP_ACC_SHUTDOWN_TP , PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT ,   PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS , PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS , PJSUA_IP_CHANGE_OP_COMPLETED }
enum	pjsua_dtmf_method { PJSUA_DTMF_METHOD_RFC2833 , PJSUA_DTMF_METHOD_SIP_INFO }
enum	pjsua_sip_timer_use { PJSUA_SIP_TIMER_INACTIVE , PJSUA_SIP_TIMER_OPTIONAL , PJSUA_SIP_TIMER_REQUIRED , PJSUA_SIP_TIMER_ALWAYS }
enum	pjsua_100rel_use { PJSUA_100REL_NOT_USED , PJSUA_100REL_MANDATORY , PJSUA_100REL_OPTIONAL }
enum	pjsua_destroy_flag { PJSUA_DESTROY_NO_RX_MSG = 1 , PJSUA_DESTROY_NO_TX_MSG = 2 , PJSUA_DESTROY_NO_NETWORK }

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)
pjsua_msg_data *	pjsua_msg_data_clone (pj_pool_t *pool, const pjsua_msg_data *rhs)
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)
pjsua_state	pjsua_get_state (void)
pj_status_t	pjsua_destroy2 (unsigned flags)
int	pjsua_handle_events (unsigned msec_timeout)
void	pjsua_stop_worker_threads (void)
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)
void	pjsua_ip_change_param_default (pjsua_ip_change_param *param)
pj_status_t	pjsua_detect_nat_type (void)
pj_status_t	pjsua_get_nat_type (pj_stun_nat_type *type)
pj_status_t	pjsua_update_stun_servers (unsigned count, pj_str_t srv[], pj_bool_t wait)
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_verify_url (const char *url)
pj_status_t	pjsua_schedule_timer (pj_timer_entry *entry, const pj_time_val *delay)
pj_status_t	pjsua_schedule_timer2 (void(*cb)(void *user_data), void *user_data, unsigned msec_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)
pj_status_t	pjsua_handle_ip_change (const pjsua_ip_change_param *param)

Detailed Description

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

Using PJSUA Library

Creating 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.

Initializing 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-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!
   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
   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:

• 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.
• 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.
• add one or more buddies with pjsua_buddy_add(). Please see PJSUA-API Buddy, Presence, and Instant Messaging section for more info.
• optionally configure the sound device, codec settings, and other media settings. Please see PJSUA-API Media Manipulation for more info.

Starting 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.

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);
       ...
   }
}

Macro Definition Documentation

DISABLED_FOR_TICKET_1185

#define DISABLED_FOR_TICKET_1185   0

Disabled features temporarily for media reorganization

PJSUA_POOL_LEN

#define PJSUA_POOL_LEN   1000

Initial memory block for PJSUA.

PJSUA_POOL_INC

#define PJSUA_POOL_INC   1000

Memory increment for PJSUA.

PJSUA_POOL_LEN_ACC

#define PJSUA_POOL_LEN_ACC   512

Initial memory block for PJSUA account.

PJSUA_POOL_INC_ACC

#define PJSUA_POOL_INC_ACC   256

Memory increment for PJSUA account.

PJSUA_ACC_MAX_PROXIES

#define PJSUA_ACC_MAX_PROXIES   8

Maximum proxies in account.

PJSUA_DEFAULT_USE_SRTP

#define PJSUA_DEFAULT_USE_SRTP   PJMEDIA_SRTP_DISABLED

Default value of SRTP mode usage. Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and PJMEDIA_SRTP_MANDATORY.

PJSUA_DEFAULT_SRTP_SECURE_SIGNALING

#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)

PJSUA_ADD_ICE_TAGS

#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

PJSUA_ACQUIRE_CALL_TIMEOUT

#define PJSUA_ACQUIRE_CALL_TIMEOUT   2000

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

Default: 2000 ms

PJSUA_HAS_VIDEO

#define PJSUA_HAS_VIDEO   PJMEDIA_HAS_VIDEO

Is video enabled.

PJSUA_VID_REQ_KEYFRAME_INTERVAL

#define PJSUA_VID_REQ_KEYFRAME_INTERVAL   3000

Interval between two keyframe requests, in milliseconds.

Default: 3000 ms

PJSUA_SEPARATE_WORKER_FOR_TIMER

#define PJSUA_SEPARATE_WORKER_FOR_TIMER   0

Specify whether timer heap events will be polled by a separate worker thread. If this is set/enabled, a worker thread will be dedicated to poll timer heap events only, and the rest worker thread(s) will poll ioqueue/network events only.

Note that if worker thread count setting (i.e: pjsua_config.thread_cnt) is set to zero, this setting will be ignored.

Default: 0 (disabled)

PJSUA_DISABLE_AUTO_SEND_100

#define PJSUA_DISABLE_AUTO_SEND_100   0

Specify whether pjsua should disable automatically sending initial answer 100/Trying for incoming calls. If disabled, application can later send 100/Trying if it wishes using pjsua_call_answer().

Default: 0 (automatic sending enabled)

PJSUA_ICE_TRANSPORT_OPTION

#define PJSUA_ICE_TRANSPORT_OPTION   0

Default options that will be passed when creating ice transport. See pjmedia_transport_ice_options.

PJSUA_TRICKLE_ICE_NEW_CAND_CHECK_INTERVAL

#define PJSUA_TRICKLE_ICE_NEW_CAND_CHECK_INTERVAL   100

Interval of checking for any new ICE candidate when trickle ICE is active. Trickle ICE gathers local ICE candidates, such as STUN and TURN candidates, in the background, while SDP offer/answer negotiation is being performed. Later, when any new ICE candidate is found, the endpoint will convey the candidate to the remote endpoint via SIP INFO.

Default: 100 ms

PJSUA_UNKNOWN_DTMF_DURATION

#define PJSUA_UNKNOWN_DTMF_DURATION   ((unsigned)-1)

Constant to specify unknown duration in pjsua_dtmf_info and pjsua_dtmf_event.

pjsip_cred_dup

#define pjsip_cred_dup   pjsip_cred_info_dup

The implementation has been moved to sip_auth.h

Typedef Documentation

pjsua_call_id

typedef int pjsua_call_id

Call identification

pjsua_acc_id

typedef int pjsua_acc_id

Account identification

pjsua_buddy_id

typedef int pjsua_buddy_id

Buddy identification

pjsua_player_id

typedef int pjsua_player_id

File player identification

pjsua_recorder_id

typedef int pjsua_recorder_id

File recorder identification

pjsua_conf_port_id

typedef int pjsua_conf_port_id

Conference port identification

pjsua_med_tp_state_cb

typedef pj_status_t(* pjsua_med_tp_state_cb) (pjsua_call_id call_id, const pjsua_med_tp_state_info *info)

Type of callback to be called when media transport state is changed.

Parameters

call_id	The call ID.
info	The media transport state info.

Returns

The callback must return PJ_SUCCESS at the moment.

pj_stun_resolve_cb

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

Typedef of callback to be registered to pjsua_resolve_stun_servers() and to be called when STUN resolution completes.

Enumeration Type Documentation

pjsua_invalid_id_const_

enum pjsua_invalid_id_const_

Constant to identify invalid ID for all sorts of IDs.

pjsua_state

enum pjsua_state

This enumeration represents pjsua state.

Enumerator
PJSUA_STATE_NULL	The library has not been initialized.
PJSUA_STATE_CREATED	After pjsua_create() is called but before pjsua_init() is called.
PJSUA_STATE_INIT	After pjsua_init() is called but before pjsua_start() is called.
PJSUA_STATE_STARTING	After pjsua_start() is called but before everything is running.
PJSUA_STATE_RUNNING	After pjsua_start() is called and before pjsua_destroy() is called.
PJSUA_STATE_CLOSING	After pjsua_destroy() is called but before the function returns.

pjsua_med_tp_st

enum pjsua_med_tp_st

Enumeration of media transport state types.

Enumerator
PJSUA_MED_TP_NULL	Null, this is the state before media transport is created.
PJSUA_MED_TP_CREATING	Just before media transport is created, which can finish asynchronously later.
PJSUA_MED_TP_IDLE	Media transport creation is completed, but not initialized yet.
PJSUA_MED_TP_INIT	Initialized (media_create() has been called).
PJSUA_MED_TP_RUNNING	Running (media_start() has been called).
PJSUA_MED_TP_DISABLED	Disabled (transport is initialized, but media is being disabled).

pjsua_create_media_transport_flag

enum pjsua_create_media_transport_flag

This enumeration specifies the options for custom media transport creation.

Enumerator
PJSUA_MED_TP_CLOSE_MEMBER	This flag indicates that the media transport must also close its "member" or "child" transport when pjmedia_transport_close() is called. If this flag is not specified, then the media transport must not call pjmedia_transport_close() of its member transport.

pjsua_contact_rewrite_method

enum pjsua_contact_rewrite_method

This enumeration specifies the contact rewrite method.

Enumerator
PJSUA_CONTACT_REWRITE_UNREGISTER	The Contact update will be done by sending unregistration to the currently registered Contact, while simultaneously sending new registration (with different Call-ID) for the updated Contact.
PJSUA_CONTACT_REWRITE_NO_UNREG	The Contact update will be done in a single, current registration session, by removing the current binding (by setting its Contact's expires parameter to zero) and adding a new Contact binding, all done in a single request.
PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE	The Contact update will be done when receiving any registration final response. If this flag is not specified, contact update will only be done upon receiving 2xx response. This flag MUST be used with PJSUA_CONTACT_REWRITE_UNREGISTER or PJSUA_CONTACT_REWRITE_NO_UNREG above to specify how the Contact update should be performed when receiving 2xx response.

pjsua_ip_change_op

enum pjsua_ip_change_op

This enumeration specifies the operation when handling IP change.

Enumerator
PJSUA_IP_CHANGE_OP_NULL	Hasn't start ip change process.
PJSUA_IP_CHANGE_OP_RESTART_LIS	The restart listener process.
PJSUA_IP_CHANGE_OP_ACC_SHUTDOWN_TP	The shutdown transport process.
PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT	The update contact process.
PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS	The hanging up call process.
PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS	The re-INVITE call process.
PJSUA_IP_CHANGE_OP_COMPLETED	The ip change process has completed.

pjsua_dtmf_method

enum pjsua_dtmf_method

This enumeration specifies DTMF method.

Enumerator
PJSUA_DTMF_METHOD_RFC2833	Send DTMF using RFC2833.
PJSUA_DTMF_METHOD_SIP_INFO	Send DTMF using SIP INFO. Notes: This method is not finalized in any standard/rfc, however it is commonly used. Warning: in case the remote doesn't support SIP INFO, response might not be sent and the sender will deal this as timeout and disconnect the call.

pjsua_sip_timer_use

enum pjsua_sip_timer_use

This enumeration specifies the usage of SIP Session Timers extension.

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.
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.

pjsua_100rel_use

enum pjsua_100rel_use

This constants controls the use of 100rel extension.

Enumerator
PJSUA_100REL_NOT_USED	Not used. For UAC, support for 100rel will be indicated in Supported header so that peer can opt to use it if it wants to. As UAS, this option will NOT cause 100rel to be used even if UAC indicates that it supports this feature.
PJSUA_100REL_MANDATORY	Mandatory. UAC will place 100rel in Require header, and UAS will reject incoming calls unless it has 100rel in Supported header.
PJSUA_100REL_OPTIONAL	Optional. Similar to PJSUA_100REL_NOT_USED, except that as UAS, this option will cause 100rel to be used if UAC indicates that it supports it.

pjsua_destroy_flag

enum pjsua_destroy_flag

Flags to be given to pjsua_destroy2()

Enumerator
PJSUA_DESTROY_NO_RX_MSG	Allow sending outgoing messages (such as unregistration, event unpublication, BYEs, unsubscription, etc.), but do not wait for responses. This is useful to perform "best effort" clean up without delaying the shutdown process waiting for responses.
PJSUA_DESTROY_NO_TX_MSG	If this flag is set, do not send any outgoing messages at all. This flag is useful if application knows that the network which the messages are to be sent on is currently down.
PJSUA_DESTROY_NO_NETWORK	Do not send or receive messages during destroy. This flag is shorthand for PJSUA_DESTROY_NO_RX_MSG + PJSUA_DESTROY_NO_TX_MSG.

Function Documentation

pjsua_logging_config_default()

void pjsua_logging_config_default

(

pjsua_logging_config *

cfg

)

Use this function to initialize logging config.

Parameters

cfg	The logging config to be initialized.

pjsua_logging_config_dup()

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.

pjsua_config_default()

void pjsua_config_default

(

pjsua_config *

cfg

)

Use this function to initialize pjsua config.

Parameters

cfg	pjsua config to be initialized.

pjsua_config_dup()

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.

pjsua_msg_data_init()

void pjsua_msg_data_init

(

pjsua_msg_data *

msg_data

)

Initialize message data.

Parameters

msg_data

Message data to be initialized.

pjsua_msg_data_clone()

pjsua_msg_data * pjsua_msg_data_clone	(	pj_pool_t *	pool,
		const pjsua_msg_data *	rhs
	)

Clone message data.

Parameters

pool	Pool to allocate memory for the new message data.
rhs	Message data to be cloned.

Returns

The new message data.

pjsua_create()

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.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsua_init()

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.

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.

pjsua_start()

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.

pjsua_destroy()

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.

See also

pjsua_destroy2()

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsua_get_state()

pjsua_state pjsua_get_state

(

void

)

Retrieve pjsua state.

Returns

pjsua state.

pjsua_destroy2()

pj_status_t pjsua_destroy2

(

unsigned

flags

)

Variant of destroy with additional flags.

Parameters

flags

Combination of pjsua_destroy_flag enumeration.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsua_handle_events()

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.

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).

pjsua_stop_worker_threads()

void pjsua_stop_worker_threads

(

void

)

Signal all worker threads to quit. This will only wait until internal threads are done.

pjsua_pool_create()

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().

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.

pjsua_reconfigure_logging()

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.

Parameters

c	Logging configuration.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsua_get_pjsip_endpt()

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.

Returns

SIP endpoint instance.

pjsua_get_pjmedia_endpt()

pjmedia_endpt * pjsua_get_pjmedia_endpt

(

void

)

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

Returns

Media endpoint instance.

pjsua_get_pool_factory()

pj_pool_factory * pjsua_get_pool_factory

(

void

)

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

Returns

Pool factory currently used by PJSUA.

pjsua_ip_change_param_default()

void pjsua_ip_change_param_default

(

pjsua_ip_change_param *

param

)

Call this function to initialize pjsua_ip_change_param with default values.

Parameters

param

The IP change param to be initialized.

pjsua_detect_nat_type()

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.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsua_get_nat_type()

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 and on_nat_detect() callback has been called.

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.

See also

pjsua_call_get_rem_nat_type()

pjsua_update_stun_servers()

pj_status_t pjsua_update_stun_servers	(	unsigned	count,
		pj_str_t	srv[],
		pj_bool_t	wait
	)

Update the STUN servers list. The pjsua_init() must have been called before calling this function.

Parameters

count	Number of STUN server entries.
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.
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.

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 on_stun_resolution_complete().

pjsua_resolve_stun_servers()

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.

Parameters

count	Number of STUN server entries to try.
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.
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.

pjsua_cancel_stun_resolution()

pj_status_t pjsua_cancel_stun_resolution	(	void *	token,
		pj_bool_t	notify_cb
	)

Cancel pending STUN resolution which match the specified token.

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.

pjsua_verify_sip_url()

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 a valid SIP/SIPS scheme, PJ_SUCCESS will be returned.

Parameters

url	The URL, as NULL terminated string.

Returns

PJ_SUCCESS on success, or the appropriate error code.

See also

pjsua_verify_url()

pjsua_verify_url()

pj_status_t pjsua_verify_url

(

const char *

url

)

This is a utility function to verify that valid URI is given. Unlike pjsua_verify_sip_url(), this function will return PJ_SUCCESS if tel: URI is given.

Parameters

url	The URL, as NULL terminated string.

Returns

PJ_SUCCESS on success, or the appropriate error code.

See also

pjsua_verify_sip_url()

pjsua_schedule_timer()

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()

pjsua_schedule_timer2()

pj_status_t pjsua_schedule_timer2	(	void(*)(void *user_data)	cb,
		void *	user_data,
		unsigned	msec_delay
	)

Schedule a callback function to be called after a specified time interval. Note that the callback may be executed by different thread, depending on whether worker thread is enabled or not.

Parameters

cb	The callback function.
user_data	The user data.
msec_delay	The time interval in msec.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsua_cancel_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()

pjsua_perror()

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.

pjsua_dump()

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.

pjsua_handle_ip_change()

pj_status_t pjsua_handle_ip_change

(

const pjsua_ip_change_param *

param

)

Inform the stack that IP address change event was detected. The stack will:

1. Restart the listener (this step is configurable via pjsua_ip_change_param.restart_listener).
2. Shutdown the transport used by account registration (this step is configurable via pjsua_acc_config.ip_change_cfg.shutdown_tp).
3. Update contact URI by sending re-Registration (this step is configurable via a\ pjsua_acc_config.allow_contact_rewrite and a\ pjsua_acc_config.contact_rewrite_method)
4. Hangup active calls (this step is configurable via a\ pjsua_acc_config.ip_change_cfg.hangup_calls) or continue the call by sending re-INVITE (configurable via pjsua_acc_config.ip_change_cfg.reinvite_flags).

Parameters

param

The IP change parameter, have a look at pjsua_ip_change_param.

Returns

PJ_SUCCESS on success, other on error.