pjsip logo pjsip.org
Open source SIP stack and media stack for presence, im/instant messaging, and multimedia communication

HOME

SIP/media Features
High Performance SIP
Small Footprint SIP
Symbian Port

FAQ

Documentation

Licensing

Download

Development (Trac)

Projects using pjsip

Mailing List

Open Source Links


About: PJLIB, PJLIB-UTIL, PJSIP, and PJMEDIA are created by: Benny Prijono
<bennylp@pjsip.org>


 

Home --> Documentations --> PJSIP Reference

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


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:

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


Data Structures

struct  pjsua_logging_config
struct  pjsua_mwi_info
struct  pjsua_callback
struct  pjsua_config
struct  pjsua_msg_data
struct  pj_stun_resolve_result

Defines

#define PJSUA_INVALID_ID   (-1)
#define PJSUA_ACC_MAX_PROXIES   8
#define PJSUA_DEFAULT_USE_SRTP   PJMEDIA_SRTP_DISABLED
#define PJSUA_DEFAULT_SRTP_SECURE_SIGNALING   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 struct pjsua_srv_pres pjsua_srv_pres
typedef struct pjsua_msg_data pjsua_msg_data
typedef struct pjsua_media_config pjsua_media_config
typedef void(* pj_stun_resolve_cb )(const pj_stun_resolve_result *result)

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_tpjsua_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_endpointpjsua_get_pjsip_endpt (void)
pjmedia_endptpjsua_get_pjmedia_endpt (void)
pj_pool_factorypjsua_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)


Define Documentation

#define PJSUA_INVALID_ID   (-1)

Constant to identify invalid ID for all sorts of IDs.

#define PJSUA_ACC_MAX_PROXIES   8

Maximum proxies in account.

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

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

#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

Buddy identification

File player identification

File recorder identification

Conference port identification

Opaque declaration for server side presence subscription

Forward declaration for pjsua_msg_data

Forward declaration

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

Typedef of callback to be registered to pjsua_resolve_stun_servers().


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.

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.

Returns:
PJ_SUCCESS on success, or the appropriate error code.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.