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:

create SIP transport with pjsua_transport_create(). Application would to call pjsua_transport_create() for each transport types that it wants to support (for example, UDP, TCP, and TLS). Please see PJSUA-API Signaling Transport section for more info.
create one or more SIP accounts with pjsua_acc_add() or pjsua_acc_add_local(). The SIP account is used for registering with the SIP server, if any. Please see PJSUA-API Accounts Management for more info.
add one or more buddies with pjsua_buddy_add(). Please see PJSUA-API Buddy, Presence, and Instant Messaging section for more info.
optionally configure the sound device, codec settings, and other media settings. Please see PJSUA-API Media Manipulation for more info.

Starting PJSUA

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

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

C Example for Starting PJSUA

Sample code:

static pj_status_t app_run(void)
{
   pj_status_t status;

   // Start pjsua
   status = pjsua_start();
   if (status != PJ_SUCCESS) {
       pjsua_destroy();
       pjsua_perror(THIS_FILE, "Error starting pjsua", status);
       return status;
   }

   // Run application loop
   while (1) {
       char choice[10];
       
       printf("Select menu: ");
       fgets(choice, sizeof(choice), stdin);
       ...
   }
}

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_DETECT_MERGED_REQUESTS

Specify if PJSUA should check for merged requests as per RFC 3261 section 8.2.2.2. If a merged request is detected, PJSUA will automatically reply with a 482 - Loop Detected.

Default: 1 (enabled)

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.

typedef void (*pjsua_on_rejected_incoming_call_cb)(const pjsua_on_rejected_incoming_call_param *param)

Type of callback to be called when incoming call is rejected.

Param param:: The rejected call information.

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_SHUTDOWN_TP: The restart listener 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.

See also

pjsua_call_get_rem_nat_type()

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.

See also

pjsua_verify_url()

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.

See also

pjsua_verify_sip_url()

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.

See also

pjsip_endpt_schedule_timer()

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.

See also

pjsip_endpt_cancel_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:

Restart the listener (this step is configurable via pjsua_ip_change_param.restart_listener).
Shutdown the transport used by account registration (this step is configurable via pjsua_acc_config.ip_change_cfg.shutdown_tp).
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)
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_on_rejected_incoming_call_param

#include <pjsua.h>

This will contain the information passed from the callback pjsua_on_rejected_incoming_call_cb.

Public Members

pjsua_call_id call_id: The incoming call id. This will be set to PJSUA_INVALID_ID when there is no available call slot at the time.

pj_str_t local_info: Local URI.

pj_str_t remote_info: Remote URI.

int st_code: Rejection code.

pj_str_t st_text: Rejection text.

pjsip_rx_data *rdata: The original INVITE message, if it’s not available this will be set to NULL.

struct pjsua_on_rejected_incoming_call_param::[anonymous] buf_: Internal.

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), rx_event_pt (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_dlg_event_state)(pjsua_buddy_id buddy_id)

Notify application when the buddy dialog 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_buddy_evsub_dlg_event_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 dialog state 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.