pjnath/docs/doc_ice.h

/* $Id$ */
/* 
 * Copyright (C) 2008-2009 Teluu Inc. (http://www.teluu.com)
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 */

/**
@defgroup PJNATH_ICE ICE: Interactive Connectivity Establishment
@brief Interactive Connectivity Establishment (ICE)
@ingroup PJNATH
*/

/**
@defgroup PJNATH_ICE_STREAM_TRANSPORT ICE stream transport
@brief Transport for media streams using ICE
@ingroup PJNATH_ICE
 */

/**
@defgroup PJNATH_ICE_SESSION ICE Session
@brief Transport Independent ICE Session
@ingroup PJNATH_ICE
 */

/**
@addtogroup PJNATH_ICE
\section org Library organizations

See <b>Table of Contents</b> below.

\section ice_intro_sec Introduction to ICE

Interactive Connectivity Establishment (ICE) is the ultimate 
weapon a client can have in its NAT traversal solution arsenals, 
as it promises that if there is indeed one path for two clients 
to communicate, then ICE will find this path. And if there are 
more than one paths which the clients can communicate, ICE will 
use the best/most efficient one.

ICE works by combining several protocols (such as STUN and TURN) 
altogether and offering several candidate paths for the communication,
thereby maximising the chance of success, but at the same time also 
has the capability to prioritize the candidates, so that the more 
expensive alternative (namely relay) will only be used as the last
resort when else fails. ICE negotiation process involves several 
stages:

 - candidate gathering, where the client finds out all the possible 
   addresses that it can use for the communication. It may find 
   three types of candidates: host candidate to represent its 
   physical NICs, server reflexive candidate for the address that 
   has been resolved from STUN, and relay candidate for the address 
   that the client has allocated from a TURN relay.
 - prioritizing these candidates. Typically the relay candidate will
   have the lowest priority to use since it's the most expensive.
 - encoding these candidates, sending it to remote peer, and 
   negotiating it with offer-answer.
 - pairing the candidates, where it pairs every local candidates 
   with every remote candidates that it receives from the remote peer.
 - checking the connectivity for each candidate pairs.
 - concluding the result. Since every possible path combinations are 
   checked, if there is a path to communicate ICE will find it.


\section icestrans_sec Using ICE transport

The \ref PJNATH_ICE_STREAM_TRANSPORT is a ready to use object which
performs the above ICE operations as well as provides application with
interface to send and receive data using the negotiated path.

Please see \ref PJNATH_ICE_STREAM_TRANSPORT on how to use this object.


\section ice_owntransport_sec Creating custom ICE transport

If the \ref PJNATH_ICE_STREAM_TRANSPORT is not suitable for use 
for some reason, you will need to implement your own ICE transport,
by combining the \ref PJNATH_ICE_SESSION with your own means to
send and receive packets. The \ref PJNATH_ICE_STREAM_TRANSPORT 
provides the best example on how to do this.


\section ice_samples_sec Samples

The \ref ice_demo_sample sample demonstrates how to use 
\ref PJNATH_ICE_STREAM_TRANSPORT <b>without</b> using signaling 
protocol such as <b>SIP</b>. It provides  interactive user interface
to create and manage the ICE sessions as well as to exchange SDP 
with another ice_demo instance.

Also see <b>\ref samples_page</b> for other samples.
 */