← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/pjnath/docs/doc_turn.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjnath/docs/doc_turn.h
 
1
/* $Id: doc_turn.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
/**
 
22
@defgroup PJNATH_TURN TURN: Traversal Using Relays around NAT
 
23
@brief TURN protocol implementation
 
24
@ingroup PJNATH
 
25
 
 
26
\section turn_intro_sec Introduction to TURN
 
27
 
 
28
When a direct communication path cannot be found, it is necessary to
 
29
use the services of an intermediate host that acts as a relay for the
 
30
packets.  This relay typically sits in the public Internet and relays
 
31
packets between two hosts that both sit behind NATs.
 
32
 
 
33
TURN allows a host behind a NAT (called the TURN client) to request that 
 
34
another host (called the TURN server) act as a relay.  The client can 
 
35
arrange for the server to relay packets to and from certain other hosts
 
36
(called peers) and can control aspects of how the relaying is done.
 
37
The client does this by obtaining an IP address and port on the
 
38
server, called the relayed-transport-address.  When a peer sends a
 
39
packet to the relayed-transport-address, the server relays the packet
 
40
to the client.  When the client sends a data packet to the server,
 
41
the server relays it to the appropriate peer using the relayed-
 
42
transport-address as the source.
 
43
 
 
44
 
 
45
\section turn_op_sec Overview of TURN operations
 
46
 
 
47
<b>Discovering TURN server</b>.\n
 
48
Client learns the IP address of the TURN
 
49
server either through some privisioning or by querying DNS SRV records
 
50
for TURN service for the specified domain. Client may use UDP or TCP (or
 
51
TLS) to connect to the TURN server.
 
52
 
 
53
<b>Authentication</b>.\n
 
54
All TURN operations requires the use of authentication
 
55
(it uses STUN long term autentication method), hence client must be
 
56
configured with the correct credential to use the service.
 
57
 
 
58
<b>Allocation</b>.\n
 
59
Client creates one "relay port" (or called <b>relayed-transport-address</b>
 
60
in TURN terminology) in the TURN server by sending TURN \a Allocate request,
 
61
hence this process is called creating allocation. Once the allocation is 
 
62
successful, client will be given the IP address and port of the "relay 
 
63
port" in the Allocate response.
 
64
 
 
65
<b>Sending data through the relay</b>.\n
 
66
Once allocation has been created, client may send data to any remote 
 
67
endpoints (called peers in TURN terminology) via the "relay port". It does 
 
68
so by sending Send Indication to the TURN server, giving the peer address 
 
69
in the indication message. But note that at this point peers are not allowed
 
70
to send data towards the client (via the "relay port") before permission is 
 
71
installed for that peer.
 
72
 
 
73
<b>Creating permissions</b>.\n
 
74
Permission needs to be created in the TURN server so that a peer can send 
 
75
data to the client via the relay port (a peer in this case is identified by
 
76
its IP address). Without this, when the TURN server receives data from the
 
77
peer in the "relay port", it will drop this data.
 
78
 
 
79
<b>Receiving data from peers</b>.\n
 
80
Once permission has been installed for the peer, any data received by the 
 
81
TURN server (from that peer) in the "relay port" will be relayed back to 
 
82
client by using Data Indication.
 
83
 
 
84
<b>Using ChannelData</b>.\n
 
85
TURN provides optimized framing to the data by using ChannelData 
 
86
packetization. The client activates this format by sending ChannelBind 
 
87
request to the TURN server, which provides (channel) binding which maps a 
 
88
particular peer address with a channel number. Data sent or received to/for
 
89
this peer will then use ChannelData format instead of Send or Data 
 
90
Indications.
 
91
 
 
92
<b>Refreshing the allocation, permissions, and channel bindings</b>.\n
 
93
Allocations, permissions, and channel bindings need to be refreshed
 
94
periodically by client, or otherwise they will expire.
 
95
 
 
96
<b>Destroying the allocation</b>.\n
 
97
Once the "relay port" is no longer needed, client destroys the allocation
 
98
by sending Refresh request with LIFETIME attribute set to zero.
 
99
 
 
100
 
 
101
\section turn_org_sec Library organizations
 
102
 
 
103
The TURN functionalities in PJNATH primarily consist of 
 
104
\ref PJNATH_TURN_SOCK and \ref PJNATH_TURN_SESSION. Please see more
 
105
below.
 
106
 
 
107
 
 
108
\section turn_using_sec Using TURN transport
 
109
 
 
110
The \ref PJNATH_TURN_SOCK is a ready to use object for relaying
 
111
application data via a TURN server, by managing all the operations
 
112
above.
 
113
 
 
114
Among other things it provides the following features:
 
115
 - resolution of the TURN server with DNS SRV
 
116
 - interface to create allocation, permissions, and channel
 
117
   bindings
 
118
 - interface to send and receive packets through the relay
 
119
 - provides callback to notify the application about incoming data
 
120
 - managing the allocation, permissions, and channel bindings
 
121
 
 
122
Please see \ref PJNATH_TURN_SOCK for more documentation about and
 
123
on how to use this object.
 
124
 
 
125
 
 
126
\section turn_owntransport_sec Creating custom TURN transport
 
127
 
 
128
The \ref PJNATH_TURN_SESSION is a transport-independent object to
 
129
manage a client TURN session. It contains the core logic for managing
 
130
the TURN client session as listed in TURN operations above, but
 
131
in transport-independent manner (i.e. it doesn't have a socket), so
 
132
that developer can integrate TURN client functionality into existing
 
133
framework that already has its own means to send and receive data,
 
134
or to support new transport types to TURN, such as TLS.
 
135
 
 
136
You can create your own (custom) TURN transport by wrapping this
 
137
into your own object, and provide it with the means to send and
 
138
receive packets.
 
139
 
 
140
Please see \ref PJNATH_TURN_SESSION for more information.
 
141
 
 
142
 
 
143
\section turn_samples_sec Samples
 
144
 
 
145
The \ref turn_client_sample is a sample application to use the
 
146
\ref PJNATH_TURN_SOCK. Also there is a sample TURN server in
 
147
the distribution as well. 
 
148
 
 
149
Also see <b>\ref samples_page</b> for other samples.
 
150
 
 
151
 */
 
152
 
 
153
 
 
154
/**
 
155
 * @defgroup PJNATH_TURN_SOCK TURN client transport
 
156
 * @brief Client transport utilizing TURN relay
 
157
 * @ingroup PJNATH_TURN
 
158
 */
 
159
 
 
160
/**
 
161
 * @defgroup PJNATH_TURN_SESSION TURN client session
 
162
 * @brief Transport independent TURN client session
 
163
 * @ingroup PJNATH_TURN
 
164
 */