ICE Stream Transport
[Interactive Connectivity Establishment (ICE)]

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.

Typedef Documentation

typedef struct pj_ice_strans pj_ice_strans

Forward declaration for ICE stream transport.

Enumeration Type Documentation

enum pj_ice_strans_op

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

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:

	pool	Pool.
	dst	Destination.
	src	Source.

void pj_ice_strans_cfg_default ( pj_ice_strans_cfg * cfg )

Initialize ICE transport configuration with default values.

Parameters:

cfg

The 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_st	The ICE stream transport.
	new_role	The 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:

	name	Optional name for logging identification.
	cfg	Configuration.
	comp_cnt	Number of components.
	user_data	Arbitrary user data to be associated with this ICE stream transport.
	cb	Callback.
	p_ice_st	Pointer 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_st

The 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_st	The ICE stream transport.
	comp_id	Component ID.
	count	On input, it specifies the maximum number of elements. On output, it will be filled with the number of candidates copied to the array.
	cand	Array of candidates.

Returns:: PJ_SUCCESS, or the appropriate error code.

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_st	The ICE stream transport.
	comp_id	Component ID.
	cand	Pointer to receive the default candidate information.

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_st

The 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_st

The ICE stream transport.

Returns:: The running number of components.

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_st	The ICE stream transport.
	loc_ufrag	Optional pointer to receive ICE username fragment of local endpoint from the ICE session.
	loc_pwd	Optional pointer to receive ICE password of local endpoint from the ICE session.
	rem_ufrag	Optional pointer to receive ICE username fragment of remote endpoint from the ICE session.
	rem_pwd	Optional 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_st

The 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_st	The ICE stream transport.
	comp_id	Component 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_st

The 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_st	The ICE stream transport.
	role	ICE role.
	local_ufrag	Optional local username fragment.
	local_passwd	Optional 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_st	The ICE stream transport.
	comp_id	Component ID.
	data	The data or packet to be sent.
	data_len	Size of data or packet, in bytes.
	dst_addr	The destination address.
	dst_addr_len	Length 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_st

The 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_st

The 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_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_st	The ICE stream transport.
	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.
	rcand_cnt	Number of remote candidates in the array.
	rcand	Remote candidates array.

Returns:: PJ_SUCCESS, or the appropriate error code.

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_st

The ICE stream transport.

Returns:: PJ_SUCCESS, or the appropriate error code.

ICE Stream Transport [Interactive Connectivity Establishment (ICE)]

Detailed Description

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation

ICE Stream Transport
[Interactive Connectivity Establishment (ICE)]