initial commit

2021-10-29 14:41:03 -04:00
commit 636959b37b
@@ -0,0 +1,107 @@
+/* $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.
+ */
+
+