BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJNATH Reference

Transport for media streams using ICE. More...

Data Structures

struct  pj_ice_strans_cb
 
struct  pj_ice_strans_cfg
 

Typedefs

typedef struct pj_ice_strans pj_ice_strans
 

Enumerations

enum  pj_ice_strans_op {
  PJ_ICE_STRANS_OP_INIT,
  PJ_ICE_STRANS_OP_NEGOTIATION,
  PJ_ICE_STRANS_OP_KEEP_ALIVE
}
 
enum  pj_ice_strans_state {
  PJ_ICE_STRANS_STATE_NULL,
  PJ_ICE_STRANS_STATE_INIT,
  PJ_ICE_STRANS_STATE_READY,
  PJ_ICE_STRANS_STATE_SESS_READY,
  PJ_ICE_STRANS_STATE_NEGO,
  PJ_ICE_STRANS_STATE_RUNNING,
  PJ_ICE_STRANS_STATE_FAILED
}
 

Functions

void pj_ice_strans_cfg_default (pj_ice_strans_cfg *cfg)
 
void pj_ice_strans_cfg_copy (pj_pool_t *pool, pj_ice_strans_cfg *dst, const pj_ice_strans_cfg *src)
 
pj_status_t pj_ice_strans_create (const char *name, const pj_ice_strans_cfg *cfg, unsigned comp_cnt, void *user_data, const pj_ice_strans_cb *cb, pj_ice_strans **p_ice_st)
 
pj_ice_strans_state pj_ice_strans_get_state (pj_ice_strans *ice_st)
 
const char * pj_ice_strans_state_name (pj_ice_strans_state state)
 
pj_status_t pj_ice_strans_destroy (pj_ice_strans *ice_st)
 
void * pj_ice_strans_get_user_data (pj_ice_strans *ice_st)
 
pj_status_t pj_ice_strans_get_options (pj_ice_strans *ice_st, pj_ice_sess_options *opt)
 
pj_status_t pj_ice_strans_set_options (pj_ice_strans *ice_st, const pj_ice_sess_options *opt)
 
pj_grp_lock_tpj_ice_strans_get_grp_lock (pj_ice_strans *ice_st)
 
pj_status_t pj_ice_strans_init_ice (pj_ice_strans *ice_st, pj_ice_sess_role role, const pj_str_t *local_ufrag, const pj_str_t *local_passwd)
 
pj_bool_t pj_ice_strans_has_sess (pj_ice_strans *ice_st)
 
pj_bool_t pj_ice_strans_sess_is_running (pj_ice_strans *ice_st)
 
pj_bool_t pj_ice_strans_sess_is_complete (pj_ice_strans *ice_st)
 
unsigned pj_ice_strans_get_running_comp_cnt (pj_ice_strans *ice_st)
 
pj_status_t pj_ice_strans_get_ufrag_pwd (pj_ice_strans *ice_st, pj_str_t *loc_ufrag, pj_str_t *loc_pwd, pj_str_t *rem_ufrag, pj_str_t *rem_pwd)
 
unsigned pj_ice_strans_get_cands_count (pj_ice_strans *ice_st, unsigned comp_id)
 
pj_status_t pj_ice_strans_enum_cands (pj_ice_strans *ice_st, unsigned comp_id, unsigned *count, pj_ice_sess_cand cand[])
 
pj_status_t pj_ice_strans_get_def_cand (pj_ice_strans *ice_st, unsigned comp_id, pj_ice_sess_cand *cand)
 
pj_ice_sess_role pj_ice_strans_get_role (pj_ice_strans *ice_st)
 
pj_status_t pj_ice_strans_change_role (pj_ice_strans *ice_st, pj_ice_sess_role new_role)
 
pj_status_t pj_ice_strans_start_ice (pj_ice_strans *ice_st, const pj_str_t *rem_ufrag, const pj_str_t *rem_passwd, unsigned rcand_cnt, const pj_ice_sess_cand rcand[])
 
const pj_ice_sess_checkpj_ice_strans_get_valid_pair (const pj_ice_strans *ice_st, unsigned comp_id)
 
pj_status_t pj_ice_strans_stop_ice (pj_ice_strans *ice_st)
 
pj_status_t pj_ice_strans_sendto (pj_ice_strans *ice_st, unsigned comp_id, const void *data, pj_size_t data_len, const pj_sockaddr_t *dst_addr, int dst_addr_len)
 

Detailed Description

This module describes ICE stream transport, as represented by pj_ice_strans structure, and is part of PJNATH - the Open Source NAT traversal helper library.

ICE stream transport, as represented by pj_ice_strans structure, is an ICE capable class for transporting media streams within a media session. It consists of one or more transport sockets (typically two for RTP based communication - one for RTP and one for RTCP), and an ICE Session for performing connectivity checks among the. various candidates of the transport addresses.

Using the ICE stream transport

The steps below describe how to use ICE session:

  • initialize a pj_ice_strans_cfg structure. This contains various settings for the ICE stream transport, and among other things contains the STUN and TURN settings.

  • create the instance with pj_ice_strans_create(). Among other things, the function needs the following arguments:
    • the pj_ice_strans_cfg structure for the main configurations
    • number of components to be supported
    • instance of pj_ice_strans_cb structure to report callbacks to application.

  • while the pj_ice_strans_create() call completes immediately, the initialization will be running in the background to gather the candidates (for example STUN and TURN candidates, if they are enabled in the pj_ice_strans_cfg setting). Application will be notified when the initialization completes in the on_ice_complete callback of the pj_ice_strans_cb structure (the op argument of this callback will be PJ_ICE_STRANS_OP_INIT).

  • when media stream is to be started (for example, a call is to be started), create an ICE session by calling pj_ice_strans_init_ice().

  • the application now typically will need to communicate local ICE information to remote host. It can achieve this by using the following functions to query local ICE information:
  • when the application receives remote ICE information (for example, from the SDP received from remote), it can now start ICE negotiation, by calling pj_ice_strans_start_ice(). This function requires some information about remote ICE agent such as remote ICE username fragment and password as well as array of remote candidates.

  • note that the PJNATH library does not work with SDP; application would need to encode and parse the SDP itself.

  • once ICE negotiation has been started, application will be notified about the completion in the on_ice_complete() callback of the pj_ice_strans_cb.

  • at any time, application may send or receive data. However the ICE stream transport may not be able to send it depending on its current state. Before ICE negotiation is started, the data will be sent using default candidate of the component. After negotiation is completed, data will be sent using the candidate from the successful/nominated pair. The ICE stream transport may not be able to send data while negotiation is in progress.

  • application sends data by using pj_ice_strans_sendto(). Incoming data will be reported in on_rx_data() callback of the pj_ice_strans_cb.

  • once the media session has finished (e.g. user hangs up the call), destroy the ICE session with pj_ice_strans_stop_ice().

  • at this point, application may destroy the ICE stream transport itself, or let it run so that it can be reused to create other ICE session. The benefit of letting the ICE stream transport alive (without any session active) is to avoid delay with the initialization, howerver keeping the transport alive means the transport needs to keep the STUN binding open by using keep-alive and also TURN allocation alive, and this will consume power which is an important issue for mobile applications.

Typedef Documentation

typedef struct pj_ice_strans pj_ice_strans

Forward declaration for ICE stream transport.

Enumeration Type Documentation

Transport operation types to be reported on on_status() callback

Enumerator
PJ_ICE_STRANS_OP_INIT 

Initialization (candidate gathering)

PJ_ICE_STRANS_OP_NEGOTIATION 

Negotiation

PJ_ICE_STRANS_OP_KEEP_ALIVE 

This operatino is used to report failure in keep-alive operation. Currently it is only used to report TURN Refresh failure.

ICE stream transport's state.

Enumerator
PJ_ICE_STRANS_STATE_NULL 

ICE stream transport is not created.

PJ_ICE_STRANS_STATE_INIT 

ICE candidate gathering process is in progress.

PJ_ICE_STRANS_STATE_READY 

ICE stream transport initialization/candidate gathering process is complete, ICE session may be created on this stream transport.

PJ_ICE_STRANS_STATE_SESS_READY 

New session has been created and the session is ready.

PJ_ICE_STRANS_STATE_NEGO 

ICE negotiation is in progress.

PJ_ICE_STRANS_STATE_RUNNING 

ICE negotiation has completed successfully and media is ready to be used.

PJ_ICE_STRANS_STATE_FAILED 

ICE negotiation has completed with failure.

Function Documentation

void pj_ice_strans_cfg_copy ( pj_pool_t pool,
pj_ice_strans_cfg dst,
const pj_ice_strans_cfg src 
)

Copy configuration.

Parameters
poolPool.
dstDestination.
srcSource.
void pj_ice_strans_cfg_default ( pj_ice_strans_cfg cfg)

Initialize ICE transport configuration with default values.

Parameters
cfgThe configuration to be initialized.
pj_status_t pj_ice_strans_change_role ( pj_ice_strans ice_st,
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. ICE session must have been initialized before this function can be called.

Parameters
ice_stThe ICE stream transport.
new_roleThe new role to be set.
Returns
PJ_SUCCESS on success, or the appropriate error.
pj_status_t pj_ice_strans_create ( const char *  name,
const pj_ice_strans_cfg cfg,
unsigned  comp_cnt,
void *  user_data,
const pj_ice_strans_cb cb,
pj_ice_strans **  p_ice_st 
)

Create and initialize the ICE stream transport with the specified parameters.

Parameters
nameOptional name for logging identification.
cfgConfiguration.
comp_cntNumber of components.
user_dataArbitrary user data to be associated with this ICE stream transport.
cbCallback.
p_ice_stPointer to receive the ICE stream transport instance.
Returns
PJ_SUCCESS if ICE stream transport is created successfully.
pj_status_t pj_ice_strans_destroy ( pj_ice_strans ice_st)

Destroy the ICE stream transport. This will destroy the ICE session inside the ICE stream transport, close all sockets and release all other resources.

Parameters
ice_stThe ICE stream transport.
Returns
PJ_SUCCESS, or the appropriate error code.
pj_status_t pj_ice_strans_enum_cands ( pj_ice_strans ice_st,
unsigned  comp_id,
unsigned *  count,
pj_ice_sess_cand  cand[] 
)

Enumerate the local candidates for the specified component.

Parameters
ice_stThe ICE stream transport.
comp_idComponent ID.
countOn input, it specifies the maximum number of elements. On output, it will be filled with the number of candidates copied to the array.
candArray of candidates.
Returns
PJ_SUCCESS, or the appropriate error code.
unsigned pj_ice_strans_get_cands_count ( pj_ice_strans ice_st,
unsigned  comp_id 
)

Get the number of local candidates for the specified component ID.

Parameters
ice_stThe ICE stream transport.
comp_idComponent ID.
Returns
The number of candidates.
pj_status_t pj_ice_strans_get_def_cand ( pj_ice_strans ice_st,
unsigned  comp_id,
pj_ice_sess_cand cand 
)

Get the default candidate for the specified component. When this function is called before ICE negotiation completes, the default candidate is selected according to local preference criteria. When this function is called after ICE negotiation completes, the default candidate is the candidate that forms the valid pair.

Parameters
ice_stThe ICE stream transport.
comp_idComponent ID.
candPointer to receive the default candidate information.
pj_grp_lock_t* pj_ice_strans_get_grp_lock ( pj_ice_strans ice_st)

Get the group lock for this ICE stream transport.

Parameters
ice_stThe ICE stream transport.
Returns
The group lock.
pj_status_t pj_ice_strans_get_options ( pj_ice_strans ice_st,
pj_ice_sess_options opt 
)

Get the value of various options of the ICE stream transport.

Parameters
ice_stThe ICE stream transport.
optThe options to be initialized with the values from the ICE stream transport.
Returns
PJ_SUCCESS on success, or the appropriate error.
pj_ice_sess_role pj_ice_strans_get_role ( pj_ice_strans ice_st)

Get the current ICE role. ICE session must have been initialized before this function can be called.

Parameters
ice_stThe ICE stream transport.
Returns
Current ICE role.
unsigned pj_ice_strans_get_running_comp_cnt ( pj_ice_strans ice_st)

Get the current/running component count. If ICE negotiation has not been started, the number of components will be equal to the number when the ICE stream transport was created. Once negotiation been started, the number of components will be the lowest number of component between local and remote agents.

Parameters
ice_stThe ICE stream transport.
Returns
The running number of components.
pj_ice_strans_state pj_ice_strans_get_state ( pj_ice_strans ice_st)

Get ICE session state.

Parameters
ice_stThe ICE stream transport.
Returns
ICE session state.
pj_status_t pj_ice_strans_get_ufrag_pwd ( pj_ice_strans ice_st,
pj_str_t loc_ufrag,
pj_str_t loc_pwd,
pj_str_t rem_ufrag,
pj_str_t rem_pwd 
)

Get the ICE username fragment and password of the ICE session. The local username fragment and password can only be retrieved once ICE session has been created with pj_ice_strans_init_ice(). The remote username fragment and password can only be retrieved once ICE session has been started with pj_ice_strans_start_ice().

Note that the string returned by this function is only valid throughout the duration of the ICE session, and the application must not modify these strings. Once the ICE session has been stopped with pj_ice_strans_stop_ice(), the pointer in the string will no longer be valid.

Parameters
ice_stThe ICE stream transport.
loc_ufragOptional pointer to receive ICE username fragment of local endpoint from the ICE session.
loc_pwdOptional pointer to receive ICE password of local endpoint from the ICE session.
rem_ufragOptional pointer to receive ICE username fragment of remote endpoint from the ICE session.
rem_pwdOptional pointer to receive ICE password of remote endpoint from the ICE session.
Returns
PJ_SUCCESS if the strings have been retrieved successfully.
void* pj_ice_strans_get_user_data ( pj_ice_strans ice_st)

Get the user data associated with the ICE stream transport.

Parameters
ice_stThe ICE stream transport.
Returns
The user data.
const pj_ice_sess_check* pj_ice_strans_get_valid_pair ( const pj_ice_strans ice_st,
unsigned  comp_id 
)

Retrieve the candidate pair that has been nominated and successfully checked for the specified component. If ICE negotiation is still in progress or it has failed, this function will return NULL.

Parameters
ice_stThe ICE stream transport.
comp_idComponent ID.
Returns
The valid pair as ICE checklist structure if the pair exist.
pj_bool_t pj_ice_strans_has_sess ( pj_ice_strans ice_st)

Check if the ICE stream transport has the ICE session created. The ICE session is created with pj_ice_strans_init_ice().

Parameters
ice_stThe ICE stream transport.
Returns
PJ_TRUE if pj_ice_strans_init_ice() has been called.
pj_status_t pj_ice_strans_init_ice ( pj_ice_strans ice_st,
pj_ice_sess_role  role,
const pj_str_t local_ufrag,
const pj_str_t local_passwd 
)

Initialize the ICE session in the ICE stream transport. When application is about to send an offer containing ICE capability, or when it receives an offer containing ICE capability, it must call this function to initialize the internal ICE session. This would register all transport address aliases for each component to the ICE session as candidates. Then application can enumerate all local candidates by calling pj_ice_strans_enum_cands(), and encode these candidates in the SDP to be sent to remote agent.

Parameters
ice_stThe ICE stream transport.
roleICE role.
local_ufragOptional local username fragment.
local_passwdOptional local password.
Returns
PJ_SUCCESS, or the appropriate error code.
pj_status_t pj_ice_strans_sendto ( pj_ice_strans ice_st,
unsigned  comp_id,
const void *  data,
pj_size_t  data_len,
const pj_sockaddr_t dst_addr,
int  dst_addr_len 
)

Send outgoing packet using this transport. Application can send data (normally RTP or RTCP packets) at any time by calling this function. This function takes a destination address as one of the arguments, and this destination address should be taken from the default transport address of the component (that is the address in SDP c= and m= lines, or in a=rtcp attribute). If ICE negotiation is in progress, this function will send the data to the destination address. Otherwise if ICE negotiation has completed successfully, this function will send the data to the nominated remote address, as negotiated by ICE.

Parameters
ice_stThe ICE stream transport.
comp_idComponent ID.
dataThe data or packet to be sent.
data_lenSize of data or packet, in bytes.
dst_addrThe destination address.
dst_addr_lenLength of destination address.
Returns
PJ_SUCCESS if data is sent successfully.
pj_bool_t pj_ice_strans_sess_is_complete ( pj_ice_strans ice_st)

Check if ICE negotiation has completed.

Parameters
ice_stThe ICE stream transport.
Returns
PJ_TRUE if ICE session has been created and the negotiation is complete.
pj_bool_t pj_ice_strans_sess_is_running ( pj_ice_strans ice_st)

Check if ICE negotiation is still running.

Parameters
ice_stThe ICE stream transport.
Returns
PJ_TRUE if ICE session has been created and ICE negotiation negotiation is in progress.
pj_status_t pj_ice_strans_set_options ( pj_ice_strans ice_st,
const pj_ice_sess_options opt 
)

Specify various options for this ICE stream transport. Application should call pj_ice_strans_get_options() to initialize the options with their default values.

Parameters
ice_stThe ICE stream transport.
optOptions to be applied to this ICE stream transport.
Returns
PJ_SUCCESS on success, or the appropriate error.
pj_status_t pj_ice_strans_start_ice ( pj_ice_strans ice_st,
const pj_str_t rem_ufrag,
const pj_str_t rem_passwd,
unsigned  rcand_cnt,
const pj_ice_sess_cand  rcand[] 
)

Start ICE connectivity checks. This function can only be called after the ICE session has been created in the ICE stream transport with pj_ice_strans_init_ice().

This function must be called once application has received remote candidate list (typically from the remote SDP). This function pairs local candidates with remote candidates, and starts ICE connectivity checks. The ICE session/transport will then notify the application via the callback when ICE connectivity checks completes, either successfully or with failure.

Parameters
ice_stThe ICE stream transport.
rem_ufragRemote ufrag, as seen in the SDP received from the remote agent.
rem_passwdRemote password, as seen in the SDP received from the remote agent.
rcand_cntNumber of remote candidates in the array.
rcandRemote candidates array.
Returns
PJ_SUCCESS, or the appropriate error code.
const char* pj_ice_strans_state_name ( pj_ice_strans_state  state)

Get string representation of ICE state.

Parameters
stateICE stream transport state.
Returns
String.
pj_status_t pj_ice_strans_stop_ice ( pj_ice_strans ice_st)

Stop and destroy the ICE session inside this media transport. Application needs to call this function once the media session is over (the call has been disconnected).

Application MAY reuse this ICE stream transport for subsequent calls. In this case, it must call pj_ice_strans_stop_ice() when the call is disconnected, and reinitialize the ICE stream transport for subsequent call with pj_ice_strans_init_ice()/pj_ice_strans_start_ice(). In this case, the ICE stream transport will maintain the internal sockets and continue to send STUN keep-alive packets and TURN Refresh request to keep the NAT binding/TURN allocation open and to detect change in STUN mapped address.

If application does not want to reuse the ICE stream transport for subsequent calls, it must call pj_ice_strans_destroy() to destroy the ICE stream transport altogether.

Parameters
ice_stThe ICE stream transport.
Returns
PJ_SUCCESS, or the appropriate error code.

 


PJNATH - Open Source NAT traversal helper library supporting STUN, TURN, and ICE
Copyright (C) 2006-2009 Teluu Inc.