D-Modem/pjproject-2.11.1/pjnath/docs/doc_ice.h

108 lines
4 KiB
C
Raw Normal View History

2021-10-30 02:41:03 +08:00
/* $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.
*/