Group PJSUA_LIB_BASE

group PJSUA_LIB_BASE

Basic application creation/initialization, logging configuration, etc.

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

Defines

DISABLED_FOR_TICKET_1185

Disabled features temporarily for media reorganization

PJSUA_POOL_LEN

Initial memory block for PJSUA.

PJSUA_POOL_INC

Memory increment for PJSUA.

PJSUA_POOL_LEN_ACC

Initial memory block for PJSUA account.

PJSUA_POOL_INC_ACC

Memory increment for PJSUA account.

PJSUA_ACC_MAX_PROXIES

Maximum proxies in account.

PJSUA_DEFAULT_USE_SRTP

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

PJSUA_DEFAULT_SRTP_SECURE_SIGNALING

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

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

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

Default: 2000 ms

PJSUA_HAS_VIDEO

Is video enabled.

PJSUA_VID_REQ_KEYFRAME_INTERVAL

Interval between two keyframe requests, in milliseconds.

Default: 3000 ms

PJSUA_SEPARATE_WORKER_FOR_TIMER

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

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

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

PJSUA_TRICKLE_ICE_NEW_CAND_CHECK_INTERVAL

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

Constant to specify unknown duration in pjsua_dtmf_info and pjsua_dtmf_event.

pjsip_cred_dup

The implementation has been moved to sip_auth.h

Typedefs

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

Param call_id

The call ID.

Param info

The media transport state info.

Return

The callback must return PJ_SUCCESS at the moment.

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.

Enums

enum pjsua_invalid_id_const_

Constant to identify invalid ID for all sorts of IDs.

Values:

enumerator PJSUA_INVALID_ID
enum pjsua_state

This enumeration represents pjsua state.

Values:

enumerator PJSUA_STATE_NULL

The library has not been initialized.

enumerator PJSUA_STATE_CREATED

After pjsua_create() is called but before pjsua_init() is called.

enumerator PJSUA_STATE_INIT

After pjsua_init() is called but before pjsua_start() is called.

enumerator PJSUA_STATE_STARTING

After pjsua_start() is called but before everything is running.

enumerator PJSUA_STATE_RUNNING

After pjsua_start() is called and before pjsua_destroy() is called.

enumerator PJSUA_STATE_CLOSING

After pjsua_destroy() is called but before the function returns.

enum pjsua_med_tp_st

Enumeration of media transport state types.

Values:

enumerator PJSUA_MED_TP_NULL

Null, this is the state before media transport is created.

enumerator PJSUA_MED_TP_CREATING

Just before media transport is created, which can finish asynchronously later.

enumerator PJSUA_MED_TP_IDLE

Media transport creation is completed, but not initialized yet.

enumerator PJSUA_MED_TP_INIT

Initialized (media_create() has been called).

enumerator PJSUA_MED_TP_RUNNING

Running (media_start() has been called).

enumerator PJSUA_MED_TP_DISABLED

Disabled (transport is initialized, but media is being disabled).

enum pjsua_create_media_transport_flag

This enumeration specifies the options for custom media transport creation.

Values:

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.

enum pjsua_contact_rewrite_method

This enumeration specifies the contact rewrite method.

Values:

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.

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

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

enum pjsua_ip_change_op

This enumeration specifies the operation when handling IP change.

Values:

enumerator PJSUA_IP_CHANGE_OP_NULL

Hasn’t start ip change process.

enumerator PJSUA_IP_CHANGE_OP_RESTART_LIS

The restart listener process.

enumerator PJSUA_IP_CHANGE_OP_ACC_SHUTDOWN_TP

The shutdown transport process.

enumerator PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT

The update contact process.

enumerator PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS

The hanging up call process.

enumerator PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS

The re-INVITE call process.

enumerator PJSUA_IP_CHANGE_OP_COMPLETED

The ip change process has completed.

enum pjsua_dtmf_method

This enumeration specifies DTMF method.

Values:

enumerator PJSUA_DTMF_METHOD_RFC2833

Send DTMF using RFC2833.

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

enum pjsua_sip_timer_use

This enumeration specifies the usage of SIP Session Timers extension.

Values:

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.

enumerator PJSUA_SIP_TIMER_OPTIONAL

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

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

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

enum pjsua_100rel_use

This constants controls the use of 100rel extension.

Values:

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.

enumerator PJSUA_100REL_MANDATORY

Mandatory. UAC will place 100rel in Require header, and UAS will reject incoming calls unless it has 100rel in Supported header.

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

enum pjsua_destroy_flag

Flags to be given to pjsua_destroy2()

Values:

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.

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

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

Functions

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.

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.

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.

See also

pjsua_destroy2()

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsua_state pjsua_get_state(void)

Retrieve pjsua state.

Returns

pjsua state.

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.

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

void pjsua_stop_worker_threads(void)

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

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.

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.

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.

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

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

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.

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.

pj_status_t pjsua_schedule_timer2(void (*cb)(void *user_data), 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.

void pjsua_cancel_timer(pj_timer_entry *entry)

Cancel the previously scheduled timer.

Parameters

entry – Timer heap entry.

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.

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.

struct pjsua_logging_config
#include <pjsua.h>

Logging configuration, which can be (optionally) specified when calling pjsua_init(). Application must call pjsua_logging_config_default() to initialize this structure with the default values.

Public Members

pj_bool_t msg_logging

Log incoming and outgoing SIP message? Yes!

unsigned level

Input verbosity level. Value 5 is reasonable.

unsigned console_level

Verbosity level for console. Value 4 is reasonable.

unsigned decor

Log decoration.

pj_str_t log_filename

Optional log filename.

unsigned log_file_flags

Additional flags to be given to pj_file_open() when opening the log file. By default, the flag is PJ_O_WRONLY. Application may set PJ_O_APPEND here so that logs are appended to existing file instead of overwriting it.

Default is 0.

void (*cb)(int level, const char *data, int len)

Optional callback function to be called to write log to application specific device. This function will be called for log messages on input verbosity level.

struct pjsua_mwi_info
#include <pjsua.h>

Structure to be passed on MWI callback.

Public Members

pjsip_evsub *evsub

Event subscription session, for reference.

pjsip_rx_data *rdata

The received NOTIFY request.

struct pjsua_reg_info
#include <pjsua.h>

Structure to be passed on registration callback.

Public Members

struct pjsip_regc_cbparam *cbparam

Parameters returned by registration callback.

pjsip_regc *regc

Client registration structure.

pj_bool_t renew

Non-zero for registration and zero for unregistration.

struct pjsua_stream_info
#include <pjsua.h>

Media stream info.

Public Members

pjmedia_type type

Media type of this stream.

pjmedia_stream_info aud

Audio stream info

pjmedia_vid_stream_info vid

Video stream info

union pjsua_stream_info::[anonymous] info

Stream info (union).

struct pjsua_stream_stat
#include <pjsua.h>

Media stream statistic.

Public Members

pjmedia_rtcp_stat rtcp

RTCP statistic.

pjmedia_jb_state jbuf

Jitter buffer statistic.

struct pjsua_on_stream_precreate_param
#include <pjsua.h>

Structure to be passed to on stream precreate callback. See on_stream_precreate().

Public Members

unsigned stream_idx

Stream index in the media session, read-only.

pjsua_stream_info stream_info

Parameters that the stream will be created from.

struct pjsua_on_stream_created_param
#include <pjsua.h>

Structure to be passed to on stream created callback. See on_stream_created2().

Public Members

pjmedia_stream *stream

The audio media stream, read-only.

unsigned stream_idx

Stream index in the audio media session, read-only.

pj_bool_t destroy_port

Specify if PJSUA should take ownership of the port returned in the port parameter below. If set to PJ_TRUE, pjmedia_port_destroy() will be called on the port when it is no longer needed.

Default: PJ_FALSE

pjmedia_port *port

On input, it specifies the audio media port of the stream. Application may modify this pointer to point to different media port to be registered to the conference bridge.

struct pjsua_med_tp_state_info
#include <pjsua.h>

Structure to be passed on media transport state callback.

Public Members

unsigned med_idx

The media index.

pjsua_med_tp_st state

The media transport state

pj_status_t status

The last error code related to the media transport state.

int sip_err_code

Optional SIP error code.

void *ext_info

Optional extended info, the content is specific for each transport type.

struct pjsua_srtp_opt
#include <pjsua.h>

Specify SRTP media transport settings.

Public Members

unsigned crypto_count

Specify the number of crypto suite settings. If set to zero, all available cryptos will be enabled. Note that available crypto names can be enumerated using pjmedia_srtp_enum_crypto().

Default is zero.

pjmedia_srtp_crypto crypto[PJMEDIA_SRTP_MAX_CRYPTOS]

Specify individual crypto suite setting and its priority order.

Notes for DTLS-SRTP keying:

  • Currently only supports these cryptos: AES_CM_128_HMAC_SHA1_80, AES_CM_128_HMAC_SHA1_32, AEAD_AES_256_GCM, and AEAD_AES_128_GCM.

  • SRTP key is not configurable.

unsigned keying_count

Specify the number of enabled keying methods. If set to zero, all keyings will be enabled. Maximum value is PJMEDIA_SRTP_MAX_KEYINGS. Note that available keying methods can be enumerated using pjmedia_srtp_enum_keying().

Default is zero (all keyings are enabled with priority order: SDES, DTLS-SRTP).

pjmedia_srtp_keying_method keying[PJMEDIA_SRTP_KEYINGS_COUNT]

Specify enabled keying methods and its priority order. Keying method with higher priority will be given earlier chance to process the SDP, for example as currently only one keying is supported in the SDP offer, keying with first priority will be likely used in the SDP offer.

union pjsua_ip_change_op_info
#include <pjsua.h>

This will contain the information of the callback on_ip_change_progress.

Public Members

int transport_id
struct pjsua_ip_change_op_info::[anonymous] lis_restart

The information from listener restart operation.

int acc_id
struct pjsua_ip_change_op_info::[anonymous] acc_shutdown_tp

The information from shutdown transport.

pjsua_acc_id acc_id
pj_bool_t is_register

SIP Register if PJ_TRUE.

int code

SIP status code received.

struct pjsua_ip_change_op_info::[anonymous] acc_update_contact

The information from updating contact.

pjsua_call_id call_id
struct pjsua_ip_change_op_info::[anonymous] acc_hangup_calls

The information from hanging up call operation.

struct pjsua_ip_change_op_info::[anonymous] acc_reinvite_calls

The information from re-Invite call operation.

struct pjsua_dtmf_info
#include <pjsua.h>

This will contain the information of the callback on_dtmf_digit2.

Public Members

pjsua_dtmf_method method

The method used to send DTMF.

unsigned digit

DTMF ASCII digit.

unsigned duration

DTMF signal duration. If the duration is unknown, this value is set to PJSUA_UNKNOWN_DTMF_DURATION.

struct pjsua_dtmf_event
#include <pjsua.h>

This will contain the information of the callback on_dtmf_event.

Public Members

pjsua_dtmf_method method

The method used to send DTMF.

unsigned timestamp

The timestamp identifying the begin of the event. Timestamp units are expressed in milliseconds. Note that this value should only be used to compare multiple events received via the same method relatively to each other, as the time-base is randomized.

unsigned digit

DTMF ASCII digit.

unsigned duration

DTMF signal duration in milliseconds. Interpretation of the duration depends on the flag PJMEDIA_STREAM_DTMF_IS_END. If PJMEDIA_STREAM_DTMF_IS_END is set, this contains the total duration of the DTMF signal or PJSUA_UNKNOWN_DTMF_DURATION if the duration is unknown. If PJMEDIA_STREAM_DTMF_IS_END is not set, this contains the duration of the DTMF signal received up to this point in time. A duration of “0” indicates an infinitely long duration.

unsigned flags

Flags indicating additional information about the DTMF event. If PJMEDIA_STREAM_DTMF_IS_UPDATE is set, the event was already indicated earlier. The new indication contains an updated event duration. If PJMEDIA_STREAM_DTMF_IS_END is set, the event has ended and this indication contains the final event duration. Note that end indications might get lost. Hence it is not guaranteed to receive an event with PJMEDIA_STREAM_DTMF_IS_END for every event.

struct pjsua_call_setting
#include <pjsua.h>

Call settings.

Public Members

unsigned flag

Bitmask of pjsua_call_flag constants.

Default: PJSUA_CALL_INCLUDE_DISABLED_MEDIA

unsigned req_keyframe_method

This flag controls what methods to request keyframe are allowed on the call. Value is bitmask of pjsua_vid_req_keyframe_method.

Default: (PJSUA_VID_REQ_KEYFRAME_SIP_INFO | PJSUA_VID_REQ_KEYFRAME_RTCP_PLI)

unsigned aud_cnt

Number of simultaneous active audio streams for this call. Setting this to zero will disable audio in this call.

Default: 1

unsigned vid_cnt

Number of simultaneous active video streams for this call. Setting this to zero will disable video in this call.

Default: 1 (if video feature is enabled, otherwise it is zero)

pjmedia_dir media_dir[PJMEDIA_MAX_SDP_MEDIA]

Media direction. This setting will only be used if the flag PJSUA_CALL_SET_MEDIA_DIR is set, and it will persist for subsequent offers or answers. For example, a media that is set as PJMEDIA_DIR_ENCODING can only mark the stream in the SDP as sendonly or inactive, but will not become sendrecv in subsequent offers and answers. Application can update the media direction in any API or callback that accepts pjsua_call_setting as a parameter, such as via pjsua_call_reinvite/update() or in on_call_rx_offer/reinvite() callback.

The index of the media dir will correspond to the provisional media in pjsua_call_info.prov_media. For offers that involve adding new medias (such as initial offer), the index will correspond to all new audio media first, then video. For example, for a new call with 2 audios and 1 video, media_dir[0] and media_dir[1] will be for the audios, and media_dir[2] video.

Default: PJMEDIA_DIR_ENCODING_DECODING

struct pjsua_callback
#include <pjsua.h>

This structure describes application callback to receive various event notification from PJSUA-API. All of these callbacks are OPTIONAL, although definitely application would want to implement some of the important callbacks (such as on_incoming_call).

Public Members

void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e)

Notify application when call state has changed. Application may then query the call info to get the detail call states by calling pjsua_call_get_info() function.

Param call_id

The call index.

Param e

Event which causes the call state to change.

void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id, pjsip_rx_data *rdata)

Notify application on incoming call.

Param acc_id

The account which match the incoming call.

Param call_id

The call id that has just been created for the call.

Param rdata

The incoming INVITE request.

void (*on_call_tsx_state)(pjsua_call_id call_id, pjsip_transaction *tsx, pjsip_event *e)

This is a general notification callback which is called whenever a transaction within the call has changed state. Application can implement this callback for example to monitor the state of outgoing requests, or to answer unhandled incoming requests (such as INFO) with a final response.

Param call_id

Call identification.

Param tsx

The transaction which has changed state.

Param e

Transaction event that caused the state change.

void (*on_call_media_state)(pjsua_call_id call_id)

Notify application when media state in the call has changed. Normal application would need to implement this callback, e.g. to connect the call’s media to sound device. When ICE is used, this callback will also be called to report ICE negotiation failure. When DTLS-SRTP is used, this callback will also be called to report DTLS negotiation failure.

Param call_id

The call index.

void (*on_call_sdp_created)(pjsua_call_id call_id, pjmedia_sdp_session *sdp, pj_pool_t *pool, const pjmedia_sdp_session *rem_sdp)

Notify application when a call has just created a local SDP (for initial or subsequent SDP offer/answer). Application can implement this callback to modify the SDP, before it is being sent and/or negotiated with remote SDP, for example to apply per account/call basis codecs priority or to add custom/proprietary SDP attributes.

Param call_id

The call index.

Param sdp

The SDP has just been created.

Param pool

The pool instance, application should use this pool to modify the SDP.

Param rem_sdp

The remote SDP, will be NULL if local is SDP offerer.

void (*on_stream_precreate)(pjsua_call_id call_id, pjsua_on_stream_precreate_param *param)

Notify application when an audio media session is about to be created (as opposed to on_stream_created() and on_stream_created2() which are called after the session has been created). The application may change some stream info parameter values, i.e: jb_init, jb_min_pre, jb_max_pre, jb_max, use_ka, rtcp_sdes_bye_disabled, jb_discard_algo (audio), codec_param->enc_fmt (video).

Param call_id

Call identification.

Param param

The on stream precreate callback parameter.

void (*on_stream_created)(pjsua_call_id call_id, pjmedia_stream *strm, unsigned stream_idx, pjmedia_port **p_port)

Notify application when audio media session is created and before it is registered to the conference bridge. Application may return different audio media port if it has added media processing port to the stream. This media port then will be added to the conference bridge instead.

Note: if implemented, on_stream_created2() callback will be called instead of this one.

Param call_id

Call identification.

Param strm

Audio media stream.

Param stream_idx

Stream index in the audio media session.

Param p_port

On input, it specifies the audio media port of the stream. Application may modify this pointer to point to different media port to be registered to the conference bridge.

void (*on_stream_created2)(pjsua_call_id call_id, pjsua_on_stream_created_param *param)

Notify application when audio media session is created and before it is registered to the conference bridge. Application may return different audio media port if it has added media processing port to the stream. This media port then will be added to the conference bridge instead.

Param call_id

Call identification.

Param param

The on stream created callback parameter.

void (*on_stream_destroyed)(pjsua_call_id call_id, pjmedia_stream *strm, unsigned stream_idx)

Notify application when audio media session has been unregistered from the conference bridge and about to be destroyed.

Param call_id

Call identification.

Param strm

Audio media stream.

Param stream_idx

Stream index in the audio media session.

void (*on_dtmf_digit)(pjsua_call_id call_id, int digit)

Notify application upon incoming DTMF digits using RFC 2833 payload formats. This callback will not be called if app implements on_dtmf_digit2() or on_dtmf_event().

Param call_id

The call index.

Param digit

DTMF ASCII digit.

void (*on_dtmf_digit2)(pjsua_call_id call_id, const pjsua_dtmf_info *info)

Notify application upon incoming DTMF digits using the method specified in pjsua_dtmf_method. This callback will not be called if app implements on_dtmf_event().

Param call_id

The call index.

Param info

The DTMF info.

void (*on_dtmf_event)(pjsua_call_id call_id, const pjsua_dtmf_event *event)

Notify application upon incoming DTMF digits using the method specified in pjsua_dtmf_method. Includes additional information about events received via RTP.

Param call_id

The call index.

Param event

The DTMF event.

void (*on_call_transfer_request)(pjsua_call_id call_id, const pj_str_t *dst, pjsip_status_code *code)

Notify application on call being transferred (i.e. REFER is received). Application can decide to accept/reject transfer request by setting the code (default is 202). When this callback is not defined, the default behavior is to accept the transfer. See also on_call_transfer_request2() callback for the version with pjsua_call_setting in the argument list.

Param call_id

The call index.

Param dst

The destination where the call will be transferred to.

Param code

Status code to be returned for the call transfer request. On input, it contains status code 202.

void (*on_call_transfer_request2)(pjsua_call_id call_id, const pj_str_t *dst, pjsip_status_code *code, pjsua_call_setting *opt)

Notify application on call being transferred (i.e. REFER is received). Application can decide to accept/reject transfer request by setting the code (default is 202). When this callback is not defined, the default behavior is to accept the transfer.

Param call_id

The call index.

Param dst

The destination where the call will be transferred to.

Param code

Status code to be returned for the call transfer request. On input, it contains status code 202.

Param opt

The current call setting, application can update this setting for the call being transferred.

void (*on_call_transfer_status)(pjsua_call_id call_id, int st_code, const pj_str_t *st_text, pj_bool_t final, pj_bool_t *p_cont)

Notify application of the status of previously sent call transfer request. Application can monitor the status of the call transfer request, for example to decide whether to terminate existing call.

Param call_id

Call ID.

Param st_code

Status progress of the transfer request.

Param st_text

Status progress text.

Param final

If non-zero, no further notification will be reported. The st_code specified in this callback is the final status.

Param p_cont

Initially will be set to non-zero, application can set this to FALSE if it no longer wants to receie further notification (for example, after it hangs up the call).

void (*on_call_replace_request)(pjsua_call_id call_id, pjsip_rx_data *rdata, int *st_code, pj_str_t *st_text)

Notify application about incoming INVITE with Replaces header. Application may reject the request by setting non-2xx code. See also on_call_replace_request2() callback for the version with pjsua_call_setting in the argument list.

Param call_id

The call ID to be replaced.

Param rdata

The incoming INVITE request to replace the call.

Param st_code

Status code to be set by application. Application should only return a final status (200-699).

Param st_text

Optional status text to be set by application.

void (*on_call_replace_request2)(pjsua_call_id call_id, pjsip_rx_data *rdata, int *st_code, pj_str_t *st_text, pjsua_call_setting *opt)

Notify application about incoming INVITE with Replaces header. Application may reject the request by setting non-2xx code.

Param call_id

The call ID to be replaced.

Param rdata

The incoming INVITE request to replace the call.

Param st_code

Status code to be set by application. Application should only return a final status (200-699).

Param st_text

Optional status text to be set by application.

Param opt

The current call setting, application can update this setting for the call being replaced.

void (*on_call_replaced)(pjsua_call_id old_call_id, pjsua_call_id new_call_id)

Notify application that an existing call has been replaced with a new call. This happens when PJSUA-API receives incoming INVITE request with Replaces header.

After this callback is called, normally PJSUA-API will disconnect old_call_id and establish new_call_id.

Param old_call_id

Existing call which to be replaced with the new call.

Param new_call_id

The new call.

Param rdata

The incoming INVITE with Replaces request.

void (*on_call_rx_offer)(pjsua_call_id call_id, const pjmedia_sdp_session *offer, void *reserved, pjsip_status_code *code, pjsua_call_setting *opt)

Notify application when call has received new offer from remote (i.e. re-INVITE/UPDATE with SDP is received, or from the INVITE response in the case that the initial outgoing INVITE has no SDP). Application can decide to accept/reject the offer by setting the code (default is 200). If the offer is accepted, application can update the call setting to be applied in the answer. When this callback is not defined, the default behavior is to accept the offer using current call setting.

Note: this callback may not be called if on_call_rx_reinvite() is implemented.

Param call_id

The call index.

Param offer

The new offer received.

Param reserved

Reserved param, currently not used.

Param code

Status code to be returned for answering the offer. On input, it contains status code 200. Currently, valid values are only 200 and 488.

Param opt

The current call setting, application can update this setting for answering the offer.

void (*on_call_rx_reinvite)(pjsua_call_id call_id, const pjmedia_sdp_session *offer, pjsip_rx_data *rdata, void *reserved, pj_bool_t *async, pjsip_status_code *code, pjsua_call_setting *opt)

Notify application when call has received a re-INVITE with offer from the peer. It allows more fine-grained control over the response to a re-INVITE. If application sets async to PJ_TRUE, it can send the reply manually using the function pjsua_call_answer_with_sdp(). Otherwise, by default the re-INVITE will be answered automatically after the callback returns.

Currently, this callback is only called for re-INVITE with SDP, but app should be prepared to handle the case of re-INVITE without SDP.

Remarks: If manually answering at a later timing, application may need to monitor on_call_tsx_state() callback to check whether the re-INVITE is already answered automatically with 487 due to being cancelled.

Note: on_call_rx_offer() will still be called after this callback, but only if async is PJ_FALSE and code is 200.

Param call_id

The call index.

Param offer

Remote offer.

Param rdata

The received re-INVITE request.

Param reserved

Reserved param, currently not used.

Param async

On input, it is PJ_FALSE. Set to PJ_TRUE if app wants to manually answer the re-INVITE.

Param code

Status code to be returned for answering the offer. On input, it contains status code 200. Currently, valid values are only 200 and 488.

Param opt

The current call setting, application can update this setting for answering the offer.

void (*on_call_tx_offer)(pjsua_call_id call_id, void *reserved, pjsua_call_setting *opt)

Notify application when call has received INVITE with no SDP offer. Application can update the call setting (e.g: add audio/video), or enable/disable codecs, or update other media session settings from within the callback, however, as mandated by the standard (RFC3261 section 14.2), it must ensure that the update overlaps with the existing media session (in codecs, transports, or other parameters) that require support from the peer, this is to avoid the need for the peer to reject the offer.

When this callback is not defined, the default behavior is to send SDP offer using current active media session (with all enabled codecs on each media type).

Param call_id

The call index.

Param reserved

Reserved param, currently not used.

Param opt

The current call setting, application can update this setting for generating the offer.

void (*on_reg_started)(pjsua_acc_id acc_id, pj_bool_t renew)

Notify application when registration or unregistration has been initiated. Note that this only notifies the initial registration and unregistration. Once registration session is active, subsequent refresh will not cause this callback to be called.

Param acc_id

The account ID.

Param renew

Non-zero for registration and zero for unregistration.

void (*on_reg_started2)(pjsua_acc_id acc_id, pjsua_reg_info *info)

This is the alternative version of the on_reg_started() callback with pjsua_reg_info argument.

Param acc_id

The account ID.

Param info

The registration info.

void (*on_reg_state)(pjsua_acc_id acc_id)

Notify application when registration status has changed. Application may then query the account info to get the registration details.

Param acc_id

The account ID.

void (*on_reg_state2)(pjsua_acc_id acc_id, pjsua_reg_info *info)

Notify application when registration status has changed. Application may inspect the registration info to get the registration status details.

Param acc_id

The account ID.

Param info

The registration info.

void (*on_incoming_subscribe)(pjsua_acc_id acc_id, pjsua_srv_pres *srv_pres, pjsua_buddy_id buddy_id, const pj_str_t *from, pjsip_rx_data *rdata, pjsip_status_code *code, pj_str_t *reason, pjsua_msg_data *msg_data)

Notification when incoming SUBSCRIBE request is received. Application may use this callback to authorize the incoming subscribe request (e.g. ask user permission if the request should be granted).

If this callback is not implemented, all incoming presence subscription requests will be accepted.

If this callback is implemented, application has several choices on what to do with the incoming request:

  • it may reject the request immediately by specifying non-200 class final response in the code argument.

  • it may immediately accept the request by specifying 200 as the code argument. This is the default value if application doesn’t set any value to the code argument. In this case, the library will automatically send NOTIFY request upon returning from this callback.

  • it may delay the processing of the request, for example to request user permission whether to accept or reject the request. In this case, the application MUST set the code argument to 202, then IMMEDIATELY calls pjsua_pres_notify() with state PJSIP_EVSUB_STATE_PENDING and later calls pjsua_pres_notify() again to accept or reject the subscription request.

Any code other than 200 and 202 will be treated as 200.

Application MUST return from this callback immediately (e.g. it must not block in this callback while waiting for user confirmation).

Param srv_pres

Server presence subscription instance. If application delays the acceptance of the request, it will need to specify this object when calling pjsua_pres_notify().

Param acc_id

Account ID most appropriate for this request.

Param buddy_id

ID of the buddy matching the sender of the request, if any, or PJSUA_INVALID_ID if no matching buddy is found.

Param from

The From URI of the request.

Param rdata

The incoming request.

Param code

The status code to respond to the request. The default value is 200. Application may set this to other final status code to accept or reject the request.

Param reason

The reason phrase to respond to the request.

Param msg_data

If the application wants to send additional headers in the response, it can put it in this parameter.

void (*on_srv_subscribe_state)(pjsua_acc_id acc_id, pjsua_srv_pres *srv_pres, const pj_str_t *remote_uri, pjsip_evsub_state state, pjsip_event *event)

Notification when server side subscription state has changed. This callback is optional as application normally does not need to do anything to maintain server side presence subscription.

Param acc_id

The account ID.

Param srv_pres

Server presence subscription object.

Param remote_uri

Remote URI string.

Param state

New subscription state.

Param event

PJSIP event that triggers the state change.

void (*on_buddy_state)(pjsua_buddy_id buddy_id)

Notify application when the buddy state has changed. Application may then query the buddy into to get the details.

Param buddy_id

The buddy id.

void (*on_buddy_evsub_state)(pjsua_buddy_id buddy_id, pjsip_evsub *sub, pjsip_event *event)

Notify application when the state of client subscription session associated with a buddy has changed. Application may use this callback to retrieve more detailed information about the state changed event.

Param buddy_id

The buddy id.

Param sub

Event subscription session.

Param event

The event which triggers state change event.

void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, const pj_str_t *mime_type, const pj_str_t *body)

Notify application on incoming pager (i.e. MESSAGE request). Argument call_id will be -1 if MESSAGE request is not related to an existing call.

See also on_pager2() callback for the version with pjsip_rx_data passed as one of the argument.

Param call_id

Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.

Param from

URI of the sender.

Param to

URI of the destination message.

Param contact

The Contact URI of the sender, if present.

Param mime_type

MIME type of the message.

Param body

The message content.

void (*on_pager2)(pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, const pj_str_t *mime_type, const pj_str_t *body, pjsip_rx_data *rdata, pjsua_acc_id acc_id)

This is the alternative version of the on_pager() callback with pjsip_rx_data argument.

Param call_id

Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.

Param from

URI of the sender.

Param to

URI of the destination message.

Param contact

The Contact URI of the sender, if present.

Param mime_type

MIME type of the message.

Param body

The message content.

Param rdata

The incoming MESSAGE request.

Param acc_id

Account ID most suitable for this message.

void (*on_pager_status)(pjsua_call_id call_id, const pj_str_t *to, const pj_str_t *body, void *user_data, pjsip_status_code status, const pj_str_t *reason)

Notify application about the delivery status of outgoing pager request. See also on_pager_status2() callback for the version with pjsip_rx_data in the argument list.

Param call_id

Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.

Param to

Destination URI.

Param body

Message body.

Param user_data

Arbitrary data that was specified when sending IM message.

Param status

Delivery status.

Param reason

Delivery status reason.

void (*on_pager_status2)(pjsua_call_id call_id, const pj_str_t *to, const pj_str_t *body, void *user_data, pjsip_status_code status, const pj_str_t *reason, pjsip_tx_data *tdata, pjsip_rx_data *rdata, pjsua_acc_id acc_id)

Notify application about the delivery status of outgoing pager request.

Param call_id

Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.

Param to

Destination URI.

Param body

Message body.

Param user_data

Arbitrary data that was specified when sending IM message.

Param status

Delivery status.

Param reason

Delivery status reason.

Param tdata

The original MESSAGE request.

Param rdata

The incoming MESSAGE response, or NULL if the message transaction fails because of time out or transport error.

Param acc_id

Account ID from this the instant message was send.

void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, pj_bool_t is_typing)

Notify application about typing indication.

Param call_id

Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.

Param from

URI of the sender.

Param to

URI of the destination message.

Param contact

The Contact URI of the sender, if present.

Param is_typing

Non-zero if peer is typing, or zero if peer has stopped typing a message.

void (*on_typing2)(pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, pj_bool_t is_typing, pjsip_rx_data *rdata, pjsua_acc_id acc_id)

Notify application about typing indication.

Param call_id

Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.

Param from

URI of the sender.

Param to

URI of the destination message.

Param contact

The Contact URI of the sender, if present.

Param is_typing

Non-zero if peer is typing, or zero if peer has stopped typing a message.

Param rdata

The received request.

Param acc_id

Account ID most suitable for this message.

void (*on_nat_detect)(const pj_stun_nat_detect_result *res)

Callback when the library has finished performing NAT type detection.

Param res

NAT detection result.

pjsip_redirect_op (*on_call_redirected)(pjsua_call_id call_id, const pjsip_uri *target, const pjsip_event *e)

This callback is called when the call is about to resend the INVITE request to the specified target, following the previously received redirection response.

Application may accept the redirection to the specified target, reject this target only and make the session continue to try the next target in the list if such target exists, stop the whole redirection process altogether and cause the session to be disconnected, or defer the decision to ask for user confirmation.

This callback is optional. If this callback is not implemented, the default behavior is to NOT follow the redirection response.

Param call_id

The call ID.

Param target

The current target to be tried.

Param e

The event that caused this callback to be called. This could be the receipt of 3xx response, or 4xx/5xx response received for the INVITE sent to subsequent targets, or NULL if this callback is called from within pjsua_call_process_redirect() context.

Return

Action to be performed for the target. Set this parameter to one of the value below:

  • PJSIP_REDIRECT_ACCEPT: immediately accept the redirection. When set, the call will immediately resend INVITE request to the target.

  • PJSIP_REDIRECT_ACCEPT_REPLACE: immediately accept the redirection and replace the To header with the current target. When set, the call will immediately resend INVITE request to the target.

  • PJSIP_REDIRECT_REJECT: immediately reject this target. The call will continue retrying with next target if present, or disconnect the call if there is no more target to try.

  • PJSIP_REDIRECT_STOP: stop the whole redirection process and immediately disconnect the call. The on_call_state() callback will be called with PJSIP_INV_STATE_DISCONNECTED state immediately after this callback returns.

  • PJSIP_REDIRECT_PENDING: set to this value if no decision can be made immediately (for example to request confirmation from user). Application then MUST call pjsua_call_process_redirect() to either accept or reject the redirection upon getting user decision.

void (*on_mwi_state)(pjsua_acc_id acc_id, pjsip_evsub *evsub)

This callback is called when message waiting indication subscription state has changed. Application can then query the subscription state by calling pjsip_evsub_get_state().

Param acc_id

The account ID.

Param evsub

The subscription instance.

void (*on_mwi_info)(pjsua_acc_id acc_id, pjsua_mwi_info *mwi_info)

This callback is called when a NOTIFY request for message summary / message waiting indication is received.

Param acc_id

The account ID.

Param mwi_info

Structure containing details of the event, including the received NOTIFY request in the rdata field.

pjsip_tp_state_callback on_transport_state

This callback is called when transport state is changed. See also pjsip_tp_state_callback.

pjsua_med_tp_state_cb on_call_media_transport_state

This callback is called when media transport state is changed. See also pjsua_med_tp_state_cb.

void (*on_ice_transport_error)(int index, pj_ice_strans_op op, pj_status_t status, void *param)

This callback is called to report error in ICE media transport. Currently it is used to report TURN Refresh error.

Param index

Transport index.

Param op

Operation which trigger the failure.

Param status

Error status.

Param param

Additional info about the event. Currently this will always be set to NULL.

pj_status_t (*on_snd_dev_operation)(int operation)

Callback when the sound device is about to be opened or closed. This callback will be called even when null sound device or no sound device is configured by the application (i.e. the pjsua_set_null_snd_dev() and pjsua_set_no_snd_dev() APIs). Application can use the API pjsua_get_snd_dev() to get the info about which sound device is going to be opened/closed.

This callback is mostly useful when the application wants to manage the sound device by itself (i.e. with pjsua_set_no_snd_dev()), to get notified when it should open or close the sound device.

Param operation

The value will be set to 0 to signal that sound device is about to be closed, and 1 to be opened.

Return

The callback must return PJ_SUCCESS at the moment.

void (*on_call_media_event)(pjsua_call_id call_id, unsigned med_idx, pjmedia_event *event)

Notification about media events such as video notifications. This callback will most likely be called from media threads, thus application must not perform heavy processing in this callback. Especially, application must not destroy the call or media in this callback. If application needs to perform more complex tasks to handle the event, it should post the task to another thread.

Param call_id

The call id.

Param med_idx

The media stream index.

Param event

The media event.

pjmedia_transport *(*on_create_media_transport)(pjsua_call_id call_id, unsigned media_idx, pjmedia_transport *base_tp, unsigned flags)

This callback can be used by application to implement custom media transport adapter for the call, or to replace the media transport with something completely new altogether.

This callback is called when a new call is created. The library has created a media transport for the call, and it is provided as the base_tp argument of this callback. Upon returning, the callback must return an instance of media transport to be used by the call.

Param call_id

Call ID

Param media_idx

The media index in the SDP for which this media transport will be used.

Param base_tp

The media transport which otherwise will be used by the call has this callback not been implemented.

Param flags

Bitmask from pjsua_create_media_transport_flag.

Return

The callback must return an instance of media transport to be used by the call.

void (*on_create_media_transport_srtp)(pjsua_call_id call_id, unsigned media_idx, pjmedia_srtp_setting *srtp_opt)

Warning: deprecated and may be removed in future release. Application can set SRTP crypto settings (including keys) and keying methods via pjsua_srtp_opt in pjsua_config and pjsua_acc_config. See also ticket #2100.

This callback is called before SRTP media transport is created. Application can modify the SRTP setting srtp_opt to specify the cryptos & keys and keying methods which are going to be used. Note that only some fields of pjmedia_srtp_setting can be overriden from this callback, i.e: “crypto_count”, “crypto”, “keying_count”, “keying”, and “use” (only for initial INVITE), any modification in other fields will be ignored.

Param call_id

Call ID

Param media_idx

The media index in the SDP for which this SRTP media transport will be used.

Param srtp_opt

The SRTP setting. Application can modify this.

void (*on_acc_find_for_incoming)(const pjsip_rx_data *rdata, pjsua_acc_id *acc_id)

This callback can be used by application to override the account to be used to handle an incoming message. Initially, the account to be used will be calculated automatically by the library. This initial account will be used if application does not implement this callback, or application sets an invalid account upon returning from this callback.

Note that currently the incoming messages requiring account assignment are INVITE, MESSAGE, SUBSCRIBE, and unsolicited NOTIFY. This callback may be called before the callback of the SIP event itself, i.e: incoming call, pager, subscription, or unsolicited-event.

Param rdata

The incoming message.

Param acc_id

On input, initial account ID calculated automatically by the library. On output, the account ID prefered by application to handle the incoming message.

pj_stun_resolve_cb on_stun_resolution_complete

Calling pjsua_init() will initiate an async process to resolve and contact each of the STUN server entries to find which is usable. This callback is called when the process is complete, and can be used by the application to start creating and registering accounts. This way, the accounts can avoid call setup delay caused by pending STUN resolution.

See also pj_stun_resolve_cb.

void (*on_ip_change_progress)(pjsua_ip_change_op op, pj_status_t status, const pjsua_ip_change_op_info *info)

Calling pjsua_handle_ip_change() may involve different operation. This callback is called to report the progress of each enabled operation.

Param op

The operation.

Param status

The status of operation.

Param info

The info from the operation

void (*on_media_event)(pjmedia_event *event)

Notification about media events such as video notifications. This callback will most likely be called from media threads, thus application must not perform heavy processing in this callback. If application needs to perform more complex tasks to handle the event, it should post the task to another thread.

Param event

The media event.

struct pjsua_config
#include <pjsua.h>

This structure describes the settings to control the API and user agent behavior, and can be specified when calling pjsua_init(). Before setting the values, application must call pjsua_config_default() to initialize this structure with the default values.

Public Members

unsigned max_calls

Maximum calls to support (default: 4). The value specified here must be smaller than or equal to the compile time maximum settings PJSUA_MAX_CALLS. To increase this limit, the library must be recompiled with new PJSUA_MAX_CALLS value.

unsigned thread_cnt

Number of worker threads. Normally application will want to have at least one worker thread, unless when it wants to poll the library periodically, which in this case the worker thread can be set to zero.

unsigned nameserver_count

Number of nameservers. If no name server is configured, the SIP SRV resolution would be disabled, and domain will be resolved with standard pj_gethostbyname() function.

pj_str_t nameserver[4]

Array of nameservers to be used by the SIP resolver subsystem. The order of the name server specifies the priority (first name server will be used first, unless it is not reachable).

pj_bool_t force_lr

Force loose-route to be used in all route/proxy URIs (outbound_proxy and account’s proxy settings). When this setting is enabled, the library will check all the route/proxy URIs specified in the settings and append “;lr” parameter to the URI if the parameter is not present.

Default: 1

unsigned outbound_proxy_cnt

Number of outbound proxies in the outbound_proxy array.

pj_str_t outbound_proxy[4]

Specify the URL of outbound proxies to visit for all outgoing requests. The outbound proxies will be used for all accounts, and it will be used to build the route set for outgoing requests. The final route set for outgoing requests will consists of the outbound proxies and the proxy configured in the account.

pj_str_t stun_domain

Warning: deprecated, please use stun_srv field instead. To maintain backward compatibility, if stun_srv_cnt is zero then the value of this field will be copied to stun_srv field, if present.

Specify domain name to be resolved with DNS SRV resolution to get the address of the STUN server. Alternatively application may specify stun_host instead.

If DNS SRV resolution failed for this domain, then DNS A resolution will be performed only if stun_host is specified.

pj_str_t stun_host

Warning: deprecated, please use stun_srv field instead. To maintain backward compatibility, if stun_srv_cnt is zero then the value of this field will be copied to stun_srv field, if present.

Specify STUN server to be used, in “HOST[:PORT]” format. If port is not specified, default port 3478 will be used.

unsigned stun_srv_cnt

Number of STUN server entries in stun_srv array.

pj_str_t stun_srv[8]

Array of STUN servers to try. The library will try to resolve and contact each of the STUN server entry until it finds one that is usable. Each entry may be a domain name, host name, IP address, and it may contain an optional port number. For example:

  • ”pjsip.org” (domain name)

  • ”sip.pjsip.org” (host name)

  • ”pjsip.org:33478” (domain name and a non-standard port number)

  • ”10.0.0.1:3478” (IP address and port number)

When nameserver is configured in the pjsua_config.nameserver field, if entry is not an IP address, it will be resolved with DNS SRV resolution first, and it will fallback to use DNS A resolution if this fails. Port number may be specified even if the entry is a domain name, in case the DNS SRV resolution should fallback to a non-standard port.

When nameserver is not configured, entries will be resolved with pj_gethostbyname() if it’s not an IP address. Port number may be specified if the server is not listening in standard STUN port.

pj_bool_t stun_try_ipv6

This specifies if the library should try to do an IPv6 resolution of the STUN servers if the IPv4 resolution fails. It can be useful in an IPv6-only environment, including on NAT64.

Default: PJ_FALSE

pj_bool_t stun_ignore_failure

This specifies if the library should ignore failure with the STUN servers. If this is set to PJ_FALSE, the library will refuse to start if it fails to resolve or contact any of the STUN servers.

This setting will also determine what happens if STUN servers are unavailable during runtime (if set to PJ_FALSE, calls will directly fail, otherwise (if PJ_TRUE) call medias will fallback to proceed as though not using STUN servers.

Default: PJ_TRUE

pj_bool_t stun_map_use_stun2

This specifies whether STUN requests for resolving socket mapped address should use the new format, i.e: having STUN magic cookie in its transaction ID.

Default: PJ_FALSE

int nat_type_in_sdp

Support for adding and parsing NAT type in the SDP to assist troubleshooting. The valid values are:

  • 0: no information will be added in SDP, and parsing is disabled.

  • 1: only the NAT type number is added.

  • 2: add both NAT type number and name.

Default: 1

pjsua_100rel_use require_100rel

Specify how the support for reliable provisional response (100rel/ PRACK) should be used by default. Note that this setting can be further customized in account configuration (pjsua_acc_config).

Default: PJSUA_100REL_NOT_USED

pjsua_sip_timer_use use_timer

Specify the usage of Session Timers for all sessions. See the pjsua_sip_timer_use for possible values. Note that this setting can be further customized in account configuration (pjsua_acc_config).

Default: PJSUA_SIP_TIMER_OPTIONAL

pj_bool_t enable_unsolicited_mwi

Handle unsolicited NOTIFY requests containing message waiting indication (MWI) info. Unsolicited MWI is incoming NOTIFY requests which are not requested by client with SUBSCRIBE request.

If this is enabled, the library will respond 200/OK to the NOTIFY request and forward the request to on_mwi_info() callback.

See also mwi_enabled field #on pjsua_acc_config.

Default: PJ_TRUE

pjsip_timer_setting timer_setting

Specify Session Timer settings, see pjsip_timer_setting. Note that this setting can be further customized in account configuration (pjsua_acc_config).

unsigned cred_count

Number of credentials in the credential array.

pjsip_cred_info cred_info[8]

Array of credentials. These credentials will be used by all accounts, and can be used to authenticate against outbound proxies. If the credential is specific to the account, then application should set the credential in the pjsua_acc_config rather than the credential here.

pjsua_callback cb

Application callback to receive various event notifications from the library.

pj_str_t user_agent

Optional user agent string (default empty). If it’s empty, no User-Agent header will be sent with outgoing requests.

pjmedia_srtp_use use_srtp

Specify default value of secure media transport usage. Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and PJMEDIA_SRTP_MANDATORY.

Note that this setting can be further customized in account configuration (pjsua_acc_config).

Default: PJSUA_DEFAULT_USE_SRTP

int srtp_secure_signaling

Specify whether SRTP requires secure signaling to be used. This option is only used when use_srtp option above is non-zero.

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)

Note that this setting can be further customized in account configuration (pjsua_acc_config).

Default: PJSUA_DEFAULT_SRTP_SECURE_SIGNALING

pj_bool_t srtp_optional_dup_offer

This setting has been deprecated and will be ignored.

pjsua_srtp_opt srtp_opt

Specify SRTP transport setting. Application can initialize it with default values using pjsua_srtp_opt_default().

pj_bool_t hangup_forked_call

Disconnect other call legs when more than one 2xx responses for outgoing INVITE are received due to forking. Currently the library is not able to handle simultaneous forked media, so disconnecting the other call legs is necessary.

With this setting enabled, the library will handle only one of the connected call leg, and the other connected call legs will be disconnected.

Default: PJ_TRUE (only disable this setting for testing purposes).

pj_bool_t enable_upnp

Specify whether to enable UPnP.

Note that this setting can be further customized in account configuration (pjsua_acc_config).

Default: PJ_FALSE

pj_str_t upnp_if_name

Specify which interface to use for UPnP. If empty, UPnP will use the first suitable interface found.

Note that this setting is only applicable if UPnP is enabled and the string must be NULL terminated.

Default: empty string

struct pjsua_msg_data
#include <pjsua.h>

This structure describes additional information to be sent with outgoing SIP message. It can (optionally) be specified for example with pjsua_call_make_call(), pjsua_call_answer(), pjsua_call_hangup(), pjsua_call_set_hold(), pjsua_call_send_im(), and many more.

Application MUST call pjsua_msg_data_init() to initialize this structure before setting its values.

Forward declaration for pjsua_msg_data

Public Members

pj_str_t target_uri

Optional remote target URI (i.e. Target header). If NULL, the target will be set to the remote URI (To header). This field is used by pjsua_call_make_call(), pjsua_im_send(), pjsua_call_reinvite(), pjsua_call_set_hold(), and pjsua_call_update().

pjsip_hdr hdr_list

Additional message headers as linked list. Application can add headers to the list by creating the header, either from the heap/pool or from temporary local variable, and add the header using linked list operation. See pjsua_app.c for some sample codes.

pj_str_t content_type

MIME type of optional message body.

pj_str_t msg_body

Optional message body to be added to the message, only when the message doesn’t have a body.

pjsip_media_type multipart_ctype

Content type of the multipart body. If application wants to send multipart message bodies, it puts the parts in parts and set the content type in multipart_ctype. If the message already contains a body, the body will be added to the multipart bodies.

pjsip_multipart_part multipart_parts

List of multipart parts. If application wants to send multipart message bodies, it puts the parts in parts and set the content type in multipart_ctype. If the message already contains a body, the body will be added to the multipart bodies.

struct pj_stun_resolve_result
#include <pjsua.h>

This structure is used to represent the result of the STUN server resolution and testing, the pjsua_resolve_stun_servers() function. This structure will be passed in pj_stun_resolve_cb callback.

Forward declaration for pj_stun_resolve_result

Public Members

void *token

Arbitrary data that was passed to pjsua_resolve_stun_servers() function.

pj_status_t status

This will contain PJ_SUCCESS if at least one usable STUN server is found, otherwise it will contain the last error code during the operation.

pj_str_t name

The server name that yields successful result. This will only contain value if status is successful.

pj_sockaddr addr

The server IP address. This will only contain value if status is successful.

unsigned index

The index of the usable STUN server.

struct pjsua_ip_change_param
#include <pjsua.h>

This structure describe the parameter passed to pjsua_handle_ip_change().

Public Members

pj_bool_t restart_listener

If set to PJ_TRUE, this will restart the transport listener.

Default : PJ_TRUE

unsigned restart_lis_delay

If restart listener is set to PJ_TRUE, some delay might be needed for the listener to be restarted. Use this to set the delay.

Default : PJSUA_TRANSPORT_RESTART_DELAY_TIME

struct pjsua_ip_change_acc_cfg
#include <pjsua.h>

This structure describe the account config specific to IP address change.

Public Members

pj_bool_t shutdown_tp

Shutdown the transport used for account registration. If this is set to PJ_TRUE, the transport will be shutdown altough it’s used by multiple account. Shutdown transport will be followed by re-Registration if pjsua_acc_config.allow_contact_rewrite is enabled.

Default: PJ_TRUE

pj_bool_t hangup_calls

Hangup active calls associated with the account. If this is set to PJ_TRUE, then the calls will be hang up.

Default: PJ_FALSE

unsigned reinvite_flags

Specify the call flags used in the re-INVITE when hangup_calls is set to PJ_FALSE. If this is set to 0, no re-INVITE will be sent. The re-INVITE will be sent after re-Registration is finished.

Default: PJSUA_CALL_REINIT_MEDIA | PJSUA_CALL_UPDATE_CONTACT | PJSUA_CALL_UPDATE_VIA