Group PJNATH_ICE_SESSION

group PJNATH_ICE_SESSION

Transport Independent ICE Session.

This module describes pj_ice_sess, a transport independent ICE session, part of PJNATH - the Open Source NAT helper library.

ICE Session

An ICE session, represented by pj_ice_sess structure, is the lowest abstraction of ICE in PJNATH, and it is used to perform and manage connectivity checks of transport address candidates within a single media stream (note: this differs from what is described in ICE draft, where an ICE session manages the whole media sessions rather than just a single stream).

The ICE session described here is independent from any transports, meaning that the actual network I/O for this session would have to be performed by the application, or higher layer abstraction. Using this framework, application would give any incoming packets to the ICE session, and it would provide the ICE session with a callback to send outgoing message.

For higher abstraction of ICE where transport is included, please see ICE stream transport.

Using The ICE Session

The steps below describe how to use ICE session. Alternatively application can use the higher level ICE API, ICE stream transport, which has provided the integration of ICE with socket transport.

The steps to use ICE session is similar for both offerer and answerer:

• create ICE session with pj_ice_sess_create(). Among other things, application needs to specify:

  • STUN configuration (pj_stun_config), containing STUN settings such as timeout values and the instances of timer heap and ioqueue.

  • Session name, useful for identifying this session in the log.

  • Initial ICE role (pj_ice_sess_role). The role can be changed at later time with pj_ice_sess_change_role(), and ICE session can also change its role automatically when it detects role conflict.

  • Number of components in the media session.

  • Callback to receive ICE events (pj_ice_sess_cb)

  • Optional local ICE username and password. If these arguments are NULL, they will be generated randomly.

• Add local candidates for each component, with pj_ice_sess_add_cand(). A candidate is represented with pj_ice_sess_cand structure. Each component must be provided with at least one candidate, and all components must have the same number of candidates. Failing to comply with this will cause failure during pairing process.

• Create offer to describe local ICE candidates. ICE session does not provide a function to create such offer, but application should be able to create one since it knows about all components and candidates. If application uses ICE stream transport, it can enumerate local candidates by calling pj_ice_strans_enum_cands(). Application may use pj_ice_sess_find_default_cand() to let ICE session chooses the default transport address to be used in SDP c= and m= lines.

• Send the offer to remote endpoint using signaling such as SIP.

• Once application has received the answer, it should parse this answer, build array of remote candidates, and create check lists by calling pj_ice_sess_create_check_list(). This process is known as pairing the candidates, and will result in the creation of check lists.

• Once checklist has been created, application then can call pj_ice_sess_start_check() to instruct ICE session to start performing connectivity checks. The ICE session performs the connectivity checks by processing each check in the checklists.

• Application will be notified about the result of ICE connectivity checks via the callback that was given in pj_ice_sess_create() above.

To send data, application calls pj_ice_sess_send_data(). If ICE negotiation has not completed, ICE session would simply drop the data, and return error to caller. If ICE negotiation has completed successfully, ICE session will in turn call the on_tx_pkt callback of pj_ice_sess_cb instance that was previously registered in pj_ice_sess_create() above.

When application receives any packets on the underlying sockets, it must call pj_ice_sess_on_rx_pkt(). The ICE session will inspect the packet to decide whether to process it locally (if the packet is a STUN message and is part of ICE session) or otherwise pass it back to application via on_rx_data callback.

Enums

enum pj_ice_cand_type

This enumeration describes the type of an ICE candidate.

Values:

enumerator PJ_ICE_CAND_TYPE_HOST

ICE host candidate. A host candidate represents the actual local transport address in the host.

enumerator PJ_ICE_CAND_TYPE_SRFLX

ICE server reflexive candidate, which represents the public mapped address of the local address, and is obtained by sending STUN Binding request from the host candidate to a STUN server.

enumerator PJ_ICE_CAND_TYPE_PRFLX

ICE peer reflexive candidate, which is the address as seen by peer agent during connectivity check.

enumerator PJ_ICE_CAND_TYPE_RELAYED

ICE relayed candidate, which represents the address allocated in TURN server.

enumerator PJ_ICE_CAND_TYPE_MAX

Number of defined ICE candidate types.

enum pj_ice_sess_check_state

This enumeration describes the state of ICE check.

Values:

enumerator PJ_ICE_SESS_CHECK_STATE_FROZEN

A check for this pair hasn’t been performed, and it can’t yet be performed until some other check succeeds, allowing this pair to unfreeze and move into the Waiting state.

enumerator PJ_ICE_SESS_CHECK_STATE_WAITING

A check has not been performed for this pair, and can be performed as soon as it is the highest priority Waiting pair on the check list.

enumerator PJ_ICE_SESS_CHECK_STATE_IN_PROGRESS

A check has not been performed for this pair, and can be performed as soon as it is the highest priority Waiting pair on the check list.

enumerator PJ_ICE_SESS_CHECK_STATE_SUCCEEDED

A check has not been performed for this pair, and can be performed as soon as it is the highest priority Waiting pair on the check list.

enumerator PJ_ICE_SESS_CHECK_STATE_FAILED

A check for this pair was already done and failed, either never producing any response or producing an unrecoverable failure response.

enum pj_ice_sess_checklist_state

This enumeration describes ICE checklist state.

Values:

enumerator PJ_ICE_SESS_CHECKLIST_ST_IDLE

The checklist is not yet running.

enumerator PJ_ICE_SESS_CHECKLIST_ST_RUNNING

In this state, ICE checks are still in progress for this media stream.

enumerator PJ_ICE_SESS_CHECKLIST_ST_COMPLETED

In this state, ICE checks have completed for this media stream, either successfully or with failure.

enum pj_ice_sess_role

This enumeration describes the role of the ICE agent.

Values:

enumerator PJ_ICE_SESS_ROLE_UNKNOWN

The role is unknown.

enumerator PJ_ICE_SESS_ROLE_CONTROLLED

The ICE agent is in controlled role.

enumerator PJ_ICE_SESS_ROLE_CONTROLLING

The ICE agent is in controlling role.

enum pj_ice_sess_trickle

This enumeration describes the modes of trickle ICE.

Values:

enumerator PJ_ICE_SESS_TRICKLE_DISABLED

Trickle ICE is disabled.

enumerator PJ_ICE_SESS_TRICKLE_HALF

Half trickle ICE. This mode has better interoperability when remote capability of ICE trickle is unknown at ICE initialization.

As ICE initiator, it will convey all local ICE candidates to remote (just like regular ICE) and be ready to receive either response, trickle or regular ICE. As ICE answerer, it will do trickle ICE if it receives an offer with trickle ICE indication, otherwise it will do regular ICE.

enumerator PJ_ICE_SESS_TRICKLE_FULL

Full trickle ICE. Only use this mode if it is known that that remote supports trickle ICE. The discovery whether remote supports trickle ICE should be done prior to ICE initialization and done by application (ICE does not provide the discovery mechanism).

Functions

const char *pj_ice_get_cand_type_name(pj_ice_cand_type type)

This is a utility function to retrieve the string name for the particular candidate type.

Parameters:

type – Candidate type.

Returns:

The string representation of the candidate type.

const char *pj_ice_sess_role_name(pj_ice_sess_role role)

This is a utility function to retrieve the string name for the particular role type.

Parameters:

role – Role type.

Returns:

The string representation of the role.

void pj_ice_calc_foundation(pj_pool_t *pool, pj_str_t *foundation, pj_ice_cand_type type, const pj_sockaddr *base_addr)

This is a utility function to calculate the foundation identification for a candidate.

Parameters:

• pool – Pool to allocate the foundation string.

• foundation – Pointer to receive the foundation string.

• type – Candidate type.

• base_addr – Base address of the candidate.

void pj_ice_sess_options_default(pj_ice_sess_options *opt)

Initialize ICE session options with library default values.

Parameters:

opt – ICE session options.

pj_status_t pj_ice_sess_create(pj_stun_config *stun_cfg, const char *name, pj_ice_sess_role role, unsigned comp_cnt, const pj_ice_sess_cb *cb, const pj_str_t *local_ufrag, const pj_str_t *local_passwd, pj_grp_lock_t *grp_lock, pj_ice_sess **p_ice)

Create ICE session with the specified role and number of components. Application would typically need to create an ICE session before sending an offer or upon receiving one. After the session is created, application can register candidates to the ICE session by calling pj_ice_sess_add_cand() function.

Parameters:

• stun_cfg – The STUN configuration settings, containing among other things the timer heap instance to be used by the ICE session.

• name – Optional name to identify this ICE instance in the log file.

• role – ICE role.

• comp_cnt – Number of components.

• cb – ICE callback.

• local_ufrag – Optional string to be used as local username to authenticate incoming STUN binding request. If the value is NULL, a random string will be generated.

• local_passwd – Optional string to be used as local password.

• grp_lock – Optional group lock to be used by this session. If NULL, the session will create one itself.

• p_ice – Pointer to receive the ICE session instance.

Returns:

PJ_SUCCESS if ICE session is created successfully.

pj_status_t pj_ice_sess_get_options(pj_ice_sess *ice, pj_ice_sess_options *opt)

Get the value of various options of the ICE session.

Parameters:

• ice – The ICE session.

• opt – The options to be initialized with the values from the ICE session.

Returns:

PJ_SUCCESS on success, or the appropriate error.

pj_status_t pj_ice_sess_set_options(pj_ice_sess *ice, const pj_ice_sess_options *opt)

Specify various options for this ICE session. Application MUST only call this function after the ICE session has been created but before any connectivity check is started.

Application should call pj_ice_sess_get_options() to initialize the options with their default values.

Parameters:

• ice – The ICE session.

• opt – Options to be applied to the ICE session.

Returns:

PJ_SUCCESS on success, or the appropriate error.

pj_status_t pj_ice_sess_detach_grp_lock(pj_ice_sess *ice, pj_grp_lock_handler *handler)

Detach ICE session from group lock. This will delete ICE session group lock handler.

This function is useful when application creates an ICE session with group lock and later it needs to recreate ICE session (e.g: for ICE restart) so the previous ICE session resources can be released manually (by calling the group lock handler) without waiting for the group lock destroy to avoid memory bloat.

Parameters:

• ice – ICE session instance.

• handler – Pointer to receive the group lock handler of this ICE session.

Returns:

PJ_SUCCESS on success.

pj_status_t pj_ice_sess_destroy(pj_ice_sess *ice)

Destroy ICE session. This will cancel any connectivity checks currently running, if any, and any other events scheduled by this session, as well as all memory resources.

Parameters:

ice – ICE session instance.

Returns:

PJ_SUCCESS on success.

pj_status_t pj_ice_sess_change_role(pj_ice_sess *ice, pj_ice_sess_role new_role)

Change session role. This happens for example when ICE session was created with controlled role when receiving an offer, but it turns out that the offer contains “a=ice-lite” attribute when the SDP gets inspected.

Parameters:

• ice – The ICE session.

• new_role – The new role to be set.

Returns:

PJ_SUCCESS on success, or the appropriate error.

pj_status_t pj_ice_sess_set_prefs(pj_ice_sess *ice, const pj_uint8_t prefs[4])

Assign a custom preference values for ICE candidate types. By assigning custom preference value, application can control the order of candidates to be checked first. The default preference settings is to use 126 for host candidates, 100 for server reflexive candidates, 110 for peer reflexive candidates, an 0 for relayed candidates.

Note that this function must be called before any candidates are added to the ICE session.

Parameters:

• ice – The ICE session.

• prefs – Array of candidate preference value. The values are put in the array indexed by the candidate type as specified in pj_ice_cand_type.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_ice_sess_add_cand(pj_ice_sess *ice, unsigned comp_id, unsigned transport_id, pj_ice_cand_type type, pj_uint16_t local_pref, const pj_str_t *foundation, const pj_sockaddr_t *addr, const pj_sockaddr_t *base_addr, const pj_sockaddr_t *rel_addr, int addr_len, unsigned *p_cand_id)

Add a candidate to this ICE session. Application must add candidates for each components ID before it can start pairing the candidates and performing connectivity checks.

Parameters:

• ice – ICE session instance.

• comp_id – Component ID of this candidate.

• transport_id – Transport ID to be used to send packets for this candidate.

• type – Candidate type.

• local_pref – Local preference for this candidate, which normally should be set to 65535.

• foundation – Foundation identification.

• addr – The candidate address.

• base_addr – The candidate’s base address.

• rel_addr – Optional related address.

• addr_len – Length of addresses.

• p_cand_id – Optional pointer to receive the candidate ID.

Returns:

PJ_SUCCESS if candidate is successfully added.

pj_status_t pj_ice_sess_find_default_cand(pj_ice_sess *ice, unsigned comp_id, int *p_cand_id)

Find default candidate for the specified component ID, using this rule:

• if the component has a successful candidate pair, then the local candidate of this pair will be returned.

• otherwise a relay, reflexive, or host candidate will be selected on that specified order.

Parameters:

• ice – The ICE session instance.

• comp_id – The component ID.

• p_cand_id – Pointer to receive the candidate ID.

Returns:

PJ_SUCCESS if a candidate has been selected.

pj_status_t pj_ice_sess_create_check_list(pj_ice_sess *ice, const pj_str_t *rem_ufrag, const pj_str_t *rem_passwd, unsigned rem_cand_cnt, const pj_ice_sess_cand rem_cand[])

Pair the local and remote candidates to create check list. Application typically would call this function after receiving SDP containing ICE candidates from the remote host (either upon receiving the initial offer, for UAS, or upon receiving the answer, for UAC).

Note that ICE connectivity check will not start until application calls pj_ice_sess_start_check().

Parameters:

• ice – ICE session instance.

• rem_ufrag – Remote ufrag, as seen in the SDP received from the remote agent.

• rem_passwd – Remote password, as seen in the SDP received from the remote agent.

• rem_cand_cnt – Number of remote candidates.

• rem_cand – Remote candidate array. Remote candidates are gathered from the SDP received from the remote agent.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_ice_sess_update_check_list(pj_ice_sess *ice, const pj_str_t *rem_ufrag, const pj_str_t *rem_passwd, unsigned rem_cand_cnt, const pj_ice_sess_cand rem_cand[], pj_bool_t trickle_done)

Update check list after receiving new remote ICE candidates or after new local ICE candidates are found and conveyed to remote. This function can also be called to indicate that trickling has completed, i.e: local candidates gathering completed and remote has sent end-of-candidate indication.

This function is only applicable when trickle ICE is not disabled.

Parameters:

• ice – ICE session instance.

• rem_ufrag – Remote ufrag, as seen in the SDP received from the remote agent.

• rem_passwd – Remote password, as seen in the SDP received from the remote agent.

• rem_cand_cnt – Number of remote candidates.

• rem_cand – Remote candidate array. Remote candidates are gathered from the SDP received from the remote agent.

• trickle_done – Flag to indicate end of trickling, set to PJ_TRUE after all local candidates have been gathered AND after receiving end-of-candidate indication from remote.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_ice_sess_start_check(pj_ice_sess *ice)

Start ICE periodic check. This function will return immediately, and application will be notified about the connectivity check status in pj_ice_sess_cb callback.

Parameters:

ice – The ICE session instance.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_ice_sess_send_data(pj_ice_sess *ice, unsigned comp_id, const void *data, pj_size_t data_len)

Send data using this ICE session. If ICE checks have not produced a valid check for the specified component ID, this function will return with failure. Otherwise ICE session will send the packet to remote destination using the nominated local candidate for the specified component.

This function will in turn call on_tx_pkt function in pj_ice_sess_cb callback to actually send the packet to the wire.

Parameters:

• ice – The ICE session.

• comp_id – Component ID.

• data – The data or packet to be sent.

• data_len – Size of data or packet, in bytes.

Returns:

If the callback on_tx_pkt() is called, this will contain the return value of the callback. Otherwise, it will indicate failure with the appropriate error code.

pj_status_t pj_ice_sess_on_rx_pkt(pj_ice_sess *ice, unsigned comp_id, unsigned transport_id, void *pkt, pj_size_t pkt_size, const pj_sockaddr_t *src_addr, int src_addr_len)

Report the arrival of packet to the ICE session. Since ICE session itself doesn’t have any transports, it relies on application or higher layer component to give incoming packets to the ICE session. If the packet is not a STUN packet, this packet will be given back to application via on_rx_data() callback in pj_ice_sess_cb.

Parameters:

• ice – The ICE session.

• comp_id – Component ID.

• transport_id – Number to identify where this packet was received from. This parameter will be returned back to application in on_tx_pkt() callback.

• pkt – Incoming packet.

• pkt_size – Size of incoming packet.

• src_addr – Source address of the packet.

• src_addr_len – Length of the address.

Returns:

PJ_SUCCESS or the appropriate error code.

struct pj_ice_sess_comp

#include <ice_session.h>

This structure describes ICE component. A media stream may require multiple components, each of which has to work for the media stream as a whole to work. For media streams based on RTP, there are two components per media stream - one for RTP, and one for RTCP.

Public Members

pj_ice_sess_check *valid_check

Pointer to ICE check with highest priority which connectivity check has been successful. The value will be NULL if a no successful check has not been found for this component.

pj_ice_sess_check *nominated_check

Pointer to ICE check with highest priority which connectivity check has been successful and it has been nominated. The value may be NULL if there is no such check yet.

pj_stun_session *stun_sess

The STUN session to be used to send and receive STUN messages for this component.

struct pj_ice_msg_data

#include <ice_session.h>

Data structure to be attached to internal message processing.

Public Members

unsigned transport_id

Transport ID for this message

pj_bool_t has_req_data

Flag to indicate whether data.req contains data

union pj_ice_msg_data::data data

The data

union data

#include <ice_session.h>

The data

Public Members

struct pj_ice_msg_data::data::request_data req

Request data

struct request_data

#include <ice_session.h>

Request data

Public Members

pj_ice_sess *ice

ICE session

pj_ice_sess_checklist *clist

Checklist

unsigned ckid

Check ID

pj_ice_sess_cand *lcand

Local cand

pj_ice_sess_cand *rcand

Remote cand

struct pj_ice_sess_cand

#include <ice_session.h>

This structure describes an ICE candidate. ICE candidate is a transport address that is to be tested by ICE procedures in order to determine its suitability for usage for receipt of media. Candidates also have properties - their type (server reflexive, relayed or host), priority, foundation, and base.

Forward declaration for pj_ice_sess_cand

Public Members

unsigned id

The candidate ID.

pj_ice_cand_type type

The candidate type, as described in pj_ice_cand_type enumeration.

pj_status_t status

Status of this candidate. The value will be PJ_SUCCESS if candidate address has been resolved successfully, PJ_EPENDING when the address resolution process is in progress, or other value when the address resolution has completed with failure.

pj_uint8_t comp_id

The component ID of this candidate. Note that component IDs starts with one for RTP and two for RTCP. In other words, it’s not zero based.

pj_uint8_t transport_id

Transport ID to be used to send packets for this candidate.

pj_uint16_t local_pref

Local preference value, which typically is 65535.

pj_str_t foundation

The foundation string, which is an identifier which value will be equivalent for two candidates that are of the same type, share the same base, and come from the same STUN server. The foundation is used to optimize ICE performance in the Frozen algorithm.

pj_uint32_t prio

The candidate’s priority, a 32-bit unsigned value which value will be calculated by the ICE session when a candidate is registered to the ICE session.

pj_sockaddr addr

IP address of this candidate. For host candidates, this represents the local address of the socket. For reflexive candidates, the value will be the public address allocated in NAT router for the host candidate and as reported in MAPPED-ADDRESS or XOR-MAPPED-ADDRESS attribute of STUN Binding request. For relayed candidate, the value will be the address allocated in the TURN server by STUN Allocate request.

pj_sockaddr base_addr

Base address of this candidate. “Base” refers to the address an agent sends from for a particular candidate. For host candidates, the base is the same as the host candidate itself. For reflexive candidates, the base is the local IP address of the socket. For relayed candidates, the base address is the transport address allocated in the TURN server for this candidate.

pj_sockaddr rel_addr

Related address, which is used for informational only and is not used in any way by the ICE session.

struct pj_ice_sess_check

#include <ice_session.h>

This structure describes an ICE connectivity check. An ICE check contains a candidate pair, and will involve sending STUN Binding Request transaction for the purposes of verifying connectivity. A check is sent from the local candidate to the remote candidate of a candidate pair.

Forward declaration for pj_ice_sess_check

Public Members

pj_ice_sess_cand *lcand

Pointer to local candidate entry of this check.

pj_ice_sess_cand *rcand

Pointer to remote candidate entry of this check.

int foundation_idx

Foundation index, referring to foundation array defined in checklist.

pj_timestamp prio

Check priority.

pj_ice_sess_check_state state

Connectivity check state.

pj_stun_tx_data *tdata

STUN transmit data containing STUN Binding request that was sent as part of this check. The value will only be set when this check has a pending transaction, and is used to cancel the transaction when other check has succeeded.

pj_bool_t nominated

Flag to indicate whether this check is nominated. A nominated check contains USE-CANDIDATE attribute in its STUN Binding request.

pj_status_t err_code

When the check failed, this will contain the failure status of the STUN transaction.

struct pj_ice_sess_checklist

#include <ice_session.h>

This structure represents ICE check list, that is an ordered set of candidate pairs that an agent will use to generate checks.

Forward declaration for checklist.

Public Members

pj_ice_sess_checklist_state state

The checklist state.

unsigned count

Number of candidate pairs (checks).

pj_ice_sess_check checks[PJ_ICE_MAX_CHECKS]

Array of candidate pairs (checks).

unsigned foundation_cnt

Number of foundations.

pj_str_t foundation[PJ_ICE_MAX_CHECKS * 2]

Array of foundations, check foundation index refers to this array.

pj_timer_entry timer

A timer used to perform periodic check for this checklist.

struct pj_ice_sess_cb

#include <ice_session.h>

This structure contains callbacks that will be called by the ICE session.

Public Members

void (*on_valid_pair)(pj_ice_sess *ice)

An optional callback that will be called by the ICE session when a valid pair has been found during ICE negotiation.

Param ice:

The ICE session.

void (*on_ice_complete)(pj_ice_sess *ice, pj_status_t status)

An optional callback that will be called by the ICE session when ICE negotiation has completed, successfully or with failure.

Param ice:

The ICE session.

Param status:

Will contain PJ_SUCCESS if ICE negotiation is successful, or some error code.

pj_status_t (*on_tx_pkt)(pj_ice_sess *ice, unsigned comp_id, unsigned transport_id, const void *pkt, pj_size_t size, const pj_sockaddr_t *dst_addr, unsigned dst_addr_len)

A mandatory callback which will be called by the ICE session when it needs to send outgoing STUN packet.

Param ice:

The ICE session.

Param comp_id:

ICE component ID.

Param transport_id:

Transport ID.

Param pkt:

The STUN packet.

Param size:

The size of the packet.

Param dst_addr:

Packet destination address.

Param dst_addr_len:

Length of destination address.

void (*on_rx_data)(pj_ice_sess *ice, unsigned comp_id, unsigned transport_id, void *pkt, pj_size_t size, const pj_sockaddr_t *src_addr, unsigned src_addr_len)

A mandatory callback which will be called by the ICE session when it receives packet which is not part of ICE negotiation.

Param ice:

The ICE session.

Param comp_id:

ICE component ID.

Param transport_id:

Transport ID.

Param pkt:

The whole packet.

Param size:

Size of the packet.

Param src_addr:

Source address where this packet was received from.

Param src_addr_len:

The length of source address.

struct pj_ice_rx_check

#include <ice_session.h>

This structure represents an incoming check (an incoming Binding request message), and is mainly used to keep early checks in the list in the ICE session. An early check is a request received from remote when we haven’t received SDP answer yet, therefore we can’t perform triggered check. For such cases, keep the incoming request in a list, and we’ll do triggered checks (simultaneously) as soon as we receive answer.

Public Functions

PJ_DECL_LIST_MEMBER(struct pj_ice_rx_check)

Standard list

Public Members

unsigned comp_id

Component ID.

unsigned transport_id

Transport ID.

pj_sockaddr src_addr

Source address of request

unsigned src_addr_len

Length of src address.

pj_bool_t use_candidate

USE-CANDIDATE is present?

pj_uint32_t priority

PRIORITY value in the req.

pj_stun_uint64_attr *role_attr

ICE-CONTROLLING/CONTROLLED

struct pj_ice_sess_options

#include <ice_session.h>

This structure describes various ICE session options. Application configure the ICE session with these options by calling pj_ice_sess_set_options().

Public Members

pj_bool_t aggressive

Specify whether to use aggressive nomination. This setting can only be enabled when trickle ICE is disabled.

unsigned nominated_check_delay

For controlling agent if it uses regular nomination, specify the delay to perform nominated check (connectivity check with USE-CANDIDATE attribute) after all components have a valid pair.

Default value is PJ_ICE_NOMINATED_CHECK_DELAY.

int controlled_agent_want_nom_timeout

For a controlled agent, specify how long it wants to wait (in milliseconds) for the controlling agent to complete sending connectivity check with nominated flag set to true for all components after the controlled agent has found that all connectivity checks in its checklist have been completed and there is at least one successful (but not nominated) check for every component.

Default value for this option is ICE_CONTROLLED_AGENT_WAIT_NOMINATION_TIMEOUT. Specify -1 to disable this timer.

pj_ice_sess_trickle trickle

Trickle ICE mode. Note that, when enabled, aggressive nomination will be automatically disabled.

Default value is PJ_ICE_SESS_TRICKLE_DISABLED.

struct pj_ice_sess

#include <ice_session.h>

This structure describes the ICE session. For this version of PJNATH, an ICE session corresponds to a single media stream (unlike the ICE session described in the ICE standard where an ICE session covers the whole media and may consist of multiple media streams). The decision to support only a single media session was chosen for simplicity, while still allowing application to utilize multiple media streams by creating multiple ICE sessions, one for each media stream.

Forward declaration for pj_ice_sess

Public Members

char obj_name[PJ_MAX_OBJ_NAME]

Object name.

pj_pool_t *pool

Pool instance.

void *user_data

App. data.

pj_grp_lock_t *grp_lock

Group lock

pj_ice_sess_role role

ICE role.

pj_ice_sess_options opt

Options

pj_timestamp tie_breaker

Tie breaker value

pj_uint8_t *prefs

Type preference.

pj_bool_t is_nominating

Nominating stage

pj_bool_t is_complete

Complete?

pj_bool_t is_destroying

Destroy is called

pj_bool_t valid_pair_found

First pair found

pj_bool_t is_trickling

End-of-candidates ind sent/received?

pj_status_t ice_status

Error status.

pj_timer_entry timer

ICE timer.

pj_timer_entry timer_end_of_cand

End-of-cand timer.

pj_ice_sess_cb cb

Callback.

pj_stun_config stun_cfg

STUN settings.

pj_str_t tx_ufrag

Remote ufrag.

pj_str_t tx_uname

Uname for TX.

pj_str_t tx_pass

Remote password.

pj_str_t rx_ufrag

Local ufrag.

pj_str_t rx_uname

Uname for RX

pj_str_t rx_pass

Local password.

unsigned comp_cnt

of components.

pj_ice_sess_comp comp[PJ_ICE_MAX_COMP]

Component array

unsigned comp_ka

Next comp for KA

unsigned lcand_cnt

of local cand.

pj_ice_sess_cand lcand[PJ_ICE_MAX_CAND]

Array of cand.

unsigned lcand_paired

of local cand

paired (trickling)

unsigned rcand_cnt

of remote cand.

pj_ice_sess_cand rcand[PJ_ICE_MAX_CAND]

Array of cand.

unsigned rcand_paired

of remote cand

paired (trickling)

pj_ice_msg_data tp_data[PJ_ICE_MAX_STUN + PJ_ICE_MAX_TURN]

Array of transport datas

pj_ice_rx_check early_check

Early checks.

pj_ice_sess_checklist clist

Active checklist

pj_ice_sess_checklist valid_list

Valid list.

union pj_ice_sess::[anonymous] tmp

Temporary buffer for misc stuffs to avoid using stack too much