← Back to branch summary

~ubuntu-branches/debian/sid/sflphone/sid

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjnath/docs/doc_ice.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2013-06-02 18:04:11 UTC
  • mfrom: (1.1.9)
  • Revision ID: package-import@ubuntu.com-20130602180411-3rcpy8c1zdlo8y0s
Tags: 1.2.2-1
* New upstream release
* changeset_rb68857a4b485b7d43f92714cd5792595ff895f82.diff - fix QTest
* pjproject ./configure --disable-sound --disable-video

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjnath/docs/doc_ice.h
 
1
/* $Id: doc_ice.h 3553 2011-05-05 06:14:19Z nanang $ */
 
2
/*
 
3
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 
4
 *
 
5
 * This program is free software; you can redistribute it and/or modify
 
6
 * it under the terms of the GNU General Public License as published by
 
7
 * the Free Software Foundation; either version 2 of the License, or
 
8
 * (at your option) any later version.
 
9
 *
 
10
 * This program is distributed in the hope that it will be useful,
 
11
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
12
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
13
 * GNU General Public License for more details.
 
14
 *
 
15
 * You should have received a copy of the GNU General Public License
 
16
 * along with this program; if not, write to the Free Software
 
17
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
18
 */
 
19
 
 
20
/**
 
21
@defgroup PJNATH_ICE ICE: Interactive Connectivity Establishment
 
22
@brief Interactive Connectivity Establishment (ICE)
 
23
@ingroup PJNATH
 
24
*/
 
25
 
 
26
/**
 
27
@defgroup PJNATH_ICE_STREAM_TRANSPORT ICE stream transport
 
28
@brief Transport for media streams using ICE
 
29
@ingroup PJNATH_ICE
 
30
 */
 
31
 
 
32
/**
 
33
@defgroup PJNATH_ICE_SESSION ICE Session
 
34
@brief Transport Independent ICE Session
 
35
@ingroup PJNATH_ICE
 
36
 */
 
37
 
 
38
/**
 
39
@addtogroup PJNATH_ICE
 
40
\section org Library organizations
 
41
 
 
42
See <b>Table of Contents</b> below.
 
43
 
 
44
\section ice_intro_sec Introduction to ICE
 
45
 
 
46
Interactive Connectivity Establishment (ICE) is the ultimate
 
47
weapon a client can have in its NAT traversal solution arsenals,
 
48
as it promises that if there is indeed one path for two clients
 
49
to communicate, then ICE will find this path. And if there are
 
50
more than one paths which the clients can communicate, ICE will
 
51
use the best/most efficient one.
 
52
 
 
53
ICE works by combining several protocols (such as STUN and TURN)
 
54
altogether and offering several candidate paths for the communication,
 
55
thereby maximising the chance of success, but at the same time also
 
56
has the capability to prioritize the candidates, so that the more
 
57
expensive alternative (namely relay) will only be used as the last
 
58
resort when else fails. ICE negotiation process involves several
 
59
stages:
 
60
 
 
61
 - candidate gathering, where the client finds out all the possible
 
62
   addresses that it can use for the communication. It may find
 
63
   three types of candidates: host candidate to represent its
 
64
   physical NICs, server reflexive candidate for the address that
 
65
   has been resolved from STUN, and relay candidate for the address
 
66
   that the client has allocated from a TURN relay.
 
67
 - prioritizing these candidates. Typically the relay candidate will
 
68
   have the lowest priority to use since it's the most expensive.
 
69
 - encoding these candidates, sending it to remote peer, and
 
70
   negotiating it with offer-answer.
 
71
 - pairing the candidates, where it pairs every local candidates
 
72
   with every remote candidates that it receives from the remote peer.
 
73
 - checking the connectivity for each candidate pairs.
 
74
 - concluding the result. Since every possible path combinations are
 
75
   checked, if there is a path to communicate ICE will find it.
 
76
 
 
77
 
 
78
\section icestrans_sec Using ICE transport
 
79
 
 
80
The \ref PJNATH_ICE_STREAM_TRANSPORT is a ready to use object which
 
81
performs the above ICE operations as well as provides application with
 
82
interface to send and receive data using the negotiated path.
 
83
 
 
84
Please see \ref PJNATH_ICE_STREAM_TRANSPORT on how to use this object.
 
85
 
 
86
 
 
87
\section ice_owntransport_sec Creating custom ICE transport
 
88
 
 
89
If the \ref PJNATH_ICE_STREAM_TRANSPORT is not suitable for use
 
90
for some reason, you will need to implement your own ICE transport,
 
91
by combining the \ref PJNATH_ICE_SESSION with your own means to
 
92
send and receive packets. The \ref PJNATH_ICE_STREAM_TRANSPORT
 
93
provides the best example on how to do this.
 
94
 
 
95
 
 
96
\section ice_samples_sec Samples
 
97
 
 
98
The \ref ice_demo_sample sample demonstrates how to use
 
99
\ref PJNATH_ICE_STREAM_TRANSPORT <b>without</b> using signaling
 
100
protocol such as <b>SIP</b>. It provides  interactive user interface
 
101
to create and manage the ICE sessions as well as to exchange SDP
 
102
with another ice_demo instance.
 
103
 
 
104
Also see <b>\ref samples_page</b> for other samples.
 
105
 */