108 lines
4 KiB
C
108 lines
4 KiB
C
|
/* $Id$ */
|
||
|
|
/*
|
||
|
|
* Copyright (C) 2008-2011 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.
|
||
|
|
*/
|
||
|
|
|
||
|
|
|