diff options
Diffstat (limited to 'pjnath/docs/doc_ice.h')
-rw-r--r-- | pjnath/docs/doc_ice.h | 107 |
1 files changed, 107 insertions, 0 deletions
diff --git a/pjnath/docs/doc_ice.h b/pjnath/docs/doc_ice.h new file mode 100644 index 00000000..6f3259b7 --- /dev/null +++ b/pjnath/docs/doc_ice.h @@ -0,0 +1,107 @@ +/* $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. + */ + + |