← 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/include/pjnath/turn_sock.h

  • Committer: Package Import Robot
  • Author(s): Francois Marier, Francois Marier, Mark Purcell
  • Date: 2014-10-18 15:08:50 UTC
  • mfrom: (1.1.12)
  • mto: This revision was merged to the branch mainline in revision 29.
  • Revision ID: package-import@ubuntu.com-20141018150850-2exfk34ckb15pcwi
Tags: 1.4.1-0.1
http://bugs.debian.org/759576
http://bugs.debian.org/741130
[ Francois Marier ]
* Non-maintainer upload
* New upstream release (closes: #759576, #741130)
  - debian/rules +PJPROJECT_VERSION := 2.2.1
  - add upstream patch to fix broken TLS support
  - add patch to fix pjproject regression

[ Mark Purcell ]
* Build-Depends:
  - sflphone-daemon + libavformat-dev, libavcodec-dev, libswscale-dev,
  libavdevice-dev, libavutil-dev
  - sflphone-gnome + libclutter-gtk-1.0-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjnath/include/pjnath/turn_sock.h
1
 
/* $Id: turn_sock.h 4360 2013-02-21 11:26:35Z bennylp $ */
2
 
/* 
3
 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
 
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5
 
 *
6
 
 * This program is free software; you can redistribute it and/or modify
7
 
 * it under the terms of the GNU General Public License as published by
8
 
 * the Free Software Foundation; either version 2 of the License, or
9
 
 * (at your option) any later version.
10
 
 *
11
 
 * This program is distributed in the hope that it will be useful,
12
 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13
 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
 
 * GNU General Public License for more details.
15
 
 *
16
 
 * You should have received a copy of the GNU General Public License
17
 
 * along with this program; if not, write to the Free Software
18
 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19
 
 */
20
 
#ifndef __PJNATH_TURN_SOCK_H__
21
 
#define __PJNATH_TURN_SOCK_H__
22
 
 
23
 
/**
24
 
 * @file turn_sock.h
25
 
 * @brief TURN relay using UDP client as transport protocol
26
 
 */
27
 
#include <pjnath/turn_session.h>
28
 
#include <pj/sock_qos.h>
29
 
 
30
 
 
31
 
PJ_BEGIN_DECL
32
 
 
33
 
 
34
 
/* **************************************************************************/
35
 
/**
36
 
@addtogroup PJNATH_TURN_SOCK
37
 
@{
38
 
 
39
 
This is a ready to use object for relaying application data via a TURN server,
40
 
by managing all the operations in \ref turn_op_sec.
41
 
 
42
 
\section turnsock_using_sec Using TURN transport
43
 
 
44
 
This object provides a thin wrapper to the \ref PJNATH_TURN_SESSION, hence the
45
 
API is very much the same (apart from the obvious difference in the names).
46
 
Please see \ref PJNATH_TURN_SESSION for the documentation on how to use the
47
 
session.
48
 
 
49
 
\section turnsock_samples_sec Samples
50
 
 
51
 
The \ref turn_client_sample is a sample application to use the
52
 
\ref PJNATH_TURN_SOCK.
53
 
 
54
 
Also see <b>\ref samples_page</b> for other samples.
55
 
 
56
 
 */
57
 
 
58
 
 
59
 
/** 
60
 
 * Opaque declaration for TURN client.
61
 
 */
62
 
typedef struct pj_turn_sock pj_turn_sock;
63
 
 
64
 
/**
65
 
 * This structure contains callbacks that will be called by the TURN
66
 
 * transport.
67
 
 */
68
 
typedef struct pj_turn_sock_cb
69
 
{
70
 
    /**
71
 
     * Notification when incoming data has been received from the remote
72
 
     * peer via the TURN server. The data reported in this callback will
73
 
     * be the exact data as sent by the peer (e.g. the TURN encapsulation
74
 
     * such as Data Indication or ChannelData will be removed before this
75
 
     * function is called).
76
 
     *
77
 
     * @param turn_sock     The TURN client transport.
78
 
     * @param data          The data as received from the peer.    
79
 
     * @param data_len      Length of the data.
80
 
     * @param peer_addr     The peer address.
81
 
     * @param addr_len      The length of the peer address.
82
 
     */
83
 
    void (*on_rx_data)(pj_turn_sock *turn_sock,
84
 
                       void *pkt,
85
 
                       unsigned pkt_len,
86
 
                       const pj_sockaddr_t *peer_addr,
87
 
                       unsigned addr_len);
88
 
 
89
 
    /**
90
 
     * Notification when TURN session state has changed. Application should
91
 
     * implement this callback to monitor the progress of the TURN session.
92
 
     *
93
 
     * @param turn_sock     The TURN client transport.
94
 
     * @param old_state     Previous state.
95
 
     * @param new_state     Current state.
96
 
     */
97
 
    void (*on_state)(pj_turn_sock *turn_sock, 
98
 
                     pj_turn_state_t old_state,
99
 
                     pj_turn_state_t new_state);
100
 
 
101
 
} pj_turn_sock_cb;
102
 
 
103
 
 
104
 
/**
105
 
 * This structure describes options that can be specified when creating
106
 
 * the TURN socket. Application should call #pj_turn_sock_cfg_default()
107
 
 * to initialize this structure with its default values before using it.
108
 
 */
109
 
typedef struct pj_turn_sock_cfg
110
 
{
111
 
    /**
112
 
     * The group lock to be used by the STUN socket. If NULL, the STUN socket
113
 
     * will create one internally.
114
 
     *
115
 
     * Default: NULL
116
 
     */
117
 
    pj_grp_lock_t *grp_lock;
118
 
 
119
 
    /**
120
 
     * Packet buffer size.
121
 
     *
122
 
     * Default value is PJ_TURN_MAX_PKT_LEN.
123
 
     */
124
 
    unsigned max_pkt_size;
125
 
 
126
 
    /**
127
 
     * QoS traffic type to be set on this transport. When application wants
128
 
     * to apply QoS tagging to the transport, it's preferable to set this
129
 
     * field rather than \a qos_param fields since this is more portable.
130
 
     *
131
 
     * Default value is PJ_QOS_TYPE_BEST_EFFORT.
132
 
     */
133
 
    pj_qos_type qos_type;
134
 
 
135
 
    /**
136
 
     * Set the low level QoS parameters to the transport. This is a lower
137
 
     * level operation than setting the \a qos_type field and may not be
138
 
     * supported on all platforms.
139
 
     *
140
 
     * By default all settings in this structure are not set.
141
 
     */
142
 
    pj_qos_params qos_params;
143
 
 
144
 
    /**
145
 
     * Specify if STUN socket should ignore any errors when setting the QoS
146
 
     * traffic type/parameters.
147
 
     *
148
 
     * Default: PJ_TRUE
149
 
     */
150
 
    pj_bool_t qos_ignore_error;
151
 
 
152
 
    /**
153
 
     * Specify the interface where the socket should be bound to. If the
154
 
     * address is zero, socket will be bound to INADDR_ANY. If the address
155
 
     * is non-zero, socket will be bound to this address only. If the port is
156
 
     * set to zero, the socket will bind at any port (chosen by the OS).
157
 
     */
158
 
    pj_sockaddr bound_addr;
159
 
 
160
 
    /**
161
 
     * Specify the port range for TURN socket binding, relative to the start
162
 
     * port number specified in \a bound_addr. Note that this setting is only
163
 
     * applicable when the start port number is non zero.
164
 
     *
165
 
     * Default value is zero.
166
 
     */
167
 
    pj_uint16_t port_range;
168
 
 
169
 
} pj_turn_sock_cfg;
170
 
 
171
 
 
172
 
/**
173
 
 * Initialize pj_turn_sock_cfg structure with default values.
174
 
 */
175
 
PJ_DECL(void) pj_turn_sock_cfg_default(pj_turn_sock_cfg *cfg);
176
 
 
177
 
 
178
 
/**
179
 
 * Create a TURN transport instance with the specified address family and
180
 
 * connection type. Once TURN transport instance is created, application
181
 
 * must call pj_turn_sock_alloc() to allocate a relay address in the TURN
182
 
 * server.
183
 
 *
184
 
 * @param cfg           The STUN configuration which contains among other
185
 
 *                      things the ioqueue and timer heap instance for
186
 
 *                      the operation of this transport.
187
 
 * @param af            Address family of the client connection. Currently
188
 
 *                      pj_AF_INET() and pj_AF_INET6() are supported.
189
 
 * @param conn_type     Connection type to the TURN server. Both TCP and
190
 
 *                      UDP are supported.
191
 
 * @param cb            Callback to receive events from the TURN transport.
192
 
 * @param setting       Optional settings to be specified to the transport.
193
 
 *                      If this parameter is NULL, default values will be
194
 
 *                      used.
195
 
 * @param user_data     Arbitrary application data to be associated with
196
 
 *                      this transport.
197
 
 * @param p_turn_sock   Pointer to receive the created instance of the
198
 
 *                      TURN transport.
199
 
 *
200
 
 * @return              PJ_SUCCESS if the operation has been successful,
201
 
 *                      or the appropriate error code on failure.
202
 
 */
203
 
PJ_DECL(pj_status_t) pj_turn_sock_create(pj_stun_config *cfg,
204
 
                                         int af,
205
 
                                         pj_turn_tp_type conn_type,
206
 
                                         const pj_turn_sock_cb *cb,
207
 
                                         const pj_turn_sock_cfg *setting,
208
 
                                         void *user_data,
209
 
                                         pj_turn_sock **p_turn_sock);
210
 
 
211
 
/**
212
 
 * Destroy the TURN transport instance. This will gracefully close the
213
 
 * connection between the client and the TURN server. Although this
214
 
 * function will return immediately, the TURN socket deletion may continue
215
 
 * in the background and the application may still get state changes
216
 
 * notifications from this transport.
217
 
 *
218
 
 * @param turn_sock     The TURN transport instance.
219
 
 */
220
 
PJ_DECL(void) pj_turn_sock_destroy(pj_turn_sock *turn_sock);
221
 
 
222
 
 
223
 
/**
224
 
 * Associate a user data with this TURN transport. The user data may then
225
 
 * be retrieved later with #pj_turn_sock_get_user_data().
226
 
 *
227
 
 * @param turn_sock     The TURN transport instance.
228
 
 * @param user_data     Arbitrary data.
229
 
 *
230
 
 * @return              PJ_SUCCESS if the operation has been successful,
231
 
 *                      or the appropriate error code on failure.
232
 
 */
233
 
PJ_DECL(pj_status_t) pj_turn_sock_set_user_data(pj_turn_sock *turn_sock,
234
 
                                                void *user_data);
235
 
 
236
 
/**
237
 
 * Retrieve the previously assigned user data associated with this TURN
238
 
 * transport.
239
 
 *
240
 
 * @param turn_sock     The TURN transport instance.
241
 
 *
242
 
 * @return              The user/application data.
243
 
 */
244
 
PJ_DECL(void*) pj_turn_sock_get_user_data(pj_turn_sock *turn_sock);
245
 
 
246
 
 
247
 
/**
248
 
 * Get the TURN transport info. The transport info contains, among other
249
 
 * things, the allocated relay address.
250
 
 *
251
 
 * @param turn_sock     The TURN transport instance.
252
 
 * @param info          Pointer to be filled with TURN transport info.
253
 
 *
254
 
 * @return              PJ_SUCCESS if the operation has been successful,
255
 
 *                      or the appropriate error code on failure.
256
 
 */
257
 
PJ_DECL(pj_status_t) pj_turn_sock_get_info(pj_turn_sock *turn_sock,
258
 
                                           pj_turn_session_info *info);
259
 
 
260
 
/**
261
 
 * Acquire the internal mutex of the TURN transport. Application may need
262
 
 * to call this function to synchronize access to other objects alongside 
263
 
 * the TURN transport, to avoid deadlock.
264
 
 *
265
 
 * @param turn_sock     The TURN transport instance.
266
 
 *
267
 
 * @return              PJ_SUCCESS if the operation has been successful,
268
 
 *                      or the appropriate error code on failure.
269
 
 */
270
 
PJ_DECL(pj_status_t) pj_turn_sock_lock(pj_turn_sock *turn_sock);
271
 
 
272
 
 
273
 
/**
274
 
 * Release the internal mutex previously held with pj_turn_sock_lock().
275
 
 *
276
 
 * @param turn_sock     The TURN transport instance.
277
 
 *
278
 
 * @return              PJ_SUCCESS if the operation has been successful,
279
 
 *                      or the appropriate error code on failure.
280
 
 */
281
 
PJ_DECL(pj_status_t) pj_turn_sock_unlock(pj_turn_sock *turn_sock);
282
 
 
283
 
 
284
 
/**
285
 
 * Set STUN message logging for this TURN session. 
286
 
 * See #pj_stun_session_set_log().
287
 
 *
288
 
 * @param turn_sock     The TURN transport instance.
289
 
 * @param flags         Bitmask combination of #pj_stun_sess_msg_log_flag
290
 
 */
291
 
PJ_DECL(void) pj_turn_sock_set_log(pj_turn_sock *turn_sock,
292
 
                                   unsigned flags);
293
 
 
294
 
/**
295
 
 * Configure the SOFTWARE name to be sent in all STUN requests by the
296
 
 * TURN session.
297
 
 *
298
 
 * @param turn_sock     The TURN transport instance.
299
 
 * @param sw        Software name string. If this argument is NULL or
300
 
 *                  empty, the session will not include SOFTWARE attribute
301
 
 *                  in STUN requests and responses.
302
 
 *
303
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
304
 
 */
305
 
PJ_DECL(pj_status_t) pj_turn_sock_set_software_name(pj_turn_sock *turn_sock,
306
 
                                                    const pj_str_t *sw);
307
 
 
308
 
 
309
 
/**
310
 
 * Allocate a relay address/resource in the TURN server. This function
311
 
 * will resolve the TURN server using DNS SRV (if desired) and send TURN
312
 
 * \a Allocate request using the specified credential to allocate a relay
313
 
 * address in the server. This function completes asynchronously, and
314
 
 * application will be notified when the allocation process has been
315
 
 * successful in the \a on_state() callback when the state is set to
316
 
 * PJ_TURN_STATE_READY. If the allocation fails, the state will be set
317
 
 * to PJ_TURN_STATE_DEALLOCATING or greater.
318
 
 *
319
 
 * @param turn_sock     The TURN transport instance.
320
 
 * @param domain        The domain, hostname, or IP address of the TURN
321
 
 *                      server. When this parameter contains domain name,
322
 
 *                      the \a resolver parameter must be set to activate
323
 
 *                      DNS SRV resolution.
324
 
 * @param default_port  The default TURN port number to use when DNS SRV
325
 
 *                      resolution is not used. If DNS SRV resolution is
326
 
 *                      used, the server port number will be set from the
327
 
 *                      DNS SRV records.
328
 
 * @param resolver      If this parameter is not NULL, then the \a domain
329
 
 *                      parameter will be first resolved with DNS SRV and
330
 
 *                      then fallback to using DNS A/AAAA resolution when
331
 
 *                      DNS SRV resolution fails. If this parameter is
332
 
 *                      NULL, the \a domain parameter will be resolved as
333
 
 *                      hostname.
334
 
 * @param cred          The STUN credential to be used for the TURN server.
335
 
 * @param param         Optional TURN allocation parameter.
336
 
 *
337
 
 * @return              PJ_SUCCESS if the operation has been successfully
338
 
 *                      queued, or the appropriate error code on failure.
339
 
 *                      When this function returns PJ_SUCCESS, the final
340
 
 *                      result of the allocation process will be notified
341
 
 *                      to application in \a on_state() callback.
342
 
 *                      
343
 
 */
344
 
PJ_DECL(pj_status_t) pj_turn_sock_alloc(pj_turn_sock *turn_sock,
345
 
                                        const pj_str_t *domain,
346
 
                                        int default_port,
347
 
                                        pj_dns_resolver *resolver,
348
 
                                        const pj_stun_auth_cred *cred,
349
 
                                        const pj_turn_alloc_param *param);
350
 
 
351
 
/**
352
 
 * Create or renew permission in the TURN server for the specified peer IP
353
 
 * addresses. Application must install permission for a particular (peer)
354
 
 * IP address before it sends any data to that IP address, or otherwise
355
 
 * the TURN server will drop the data.
356
 
 *
357
 
 * @param turn_sock     The TURN transport instance.
358
 
 * @param addr_cnt      Number of IP addresses.
359
 
 * @param addr          Array of peer IP addresses. Only the address family
360
 
 *                      and IP address portion of the socket address matter.
361
 
 * @param options       Specify 1 to let the TURN client session automatically
362
 
 *                      renew the permission later when they are about to
363
 
 *                      expire.
364
 
 *
365
 
 * @return              PJ_SUCCESS if the operation has been successfully
366
 
 *                      issued, or the appropriate error code. Note that
367
 
 *                      the operation itself will complete asynchronously.
368
 
 */
369
 
PJ_DECL(pj_status_t) pj_turn_sock_set_perm(pj_turn_sock *turn_sock,
370
 
                                           unsigned addr_cnt,
371
 
                                           const pj_sockaddr addr[],
372
 
                                           unsigned options);
373
 
 
374
 
/**
375
 
 * Send a data to the specified peer address via the TURN relay. This 
376
 
 * function will encapsulate the data as STUN Send Indication or TURN
377
 
 * ChannelData packet and send the message to the TURN server. The TURN
378
 
 * server then will send the data to the peer.
379
 
 *
380
 
 * The allocation (pj_turn_sock_alloc()) must have been successfully
381
 
 * created before application can relay any data.
382
 
 *
383
 
 * @param turn_sock     The TURN transport instance.
384
 
 * @param pkt           The data/packet to be sent to peer.
385
 
 * @param pkt_len       Length of the data.
386
 
 * @param peer_addr     The remote peer address (the ultimate destination
387
 
 *                      of the data, and not the TURN server address).
388
 
 * @param addr_len      Length of the address.
389
 
 *
390
 
 * @return              PJ_SUCCESS if the operation has been successful,
391
 
 *                      or the appropriate error code on failure.
392
 
 */ 
393
 
PJ_DECL(pj_status_t) pj_turn_sock_sendto(pj_turn_sock *turn_sock,
394
 
                                        const pj_uint8_t *pkt,
395
 
                                        unsigned pkt_len,
396
 
                                        const pj_sockaddr_t *peer_addr,
397
 
                                        unsigned addr_len);
398
 
 
399
 
/**
400
 
 * Optionally establish channel binding for the specified a peer address.
401
 
 * This function will assign a unique channel number for the peer address
402
 
 * and request channel binding to the TURN server for this address. When
403
 
 * a channel has been bound to a peer, the TURN transport and TURN server
404
 
 * will exchange data using ChannelData encapsulation format, which has
405
 
 * lower bandwidth overhead than Send Indication (the default format used
406
 
 * when peer address is not bound to a channel).
407
 
 *
408
 
 * @param turn_sock     The TURN transport instance.
409
 
 * @param peer          The remote peer address.
410
 
 * @param addr_len      Length of the address.
411
 
 *
412
 
 * @return              PJ_SUCCESS if the operation has been successful,
413
 
 *                      or the appropriate error code on failure.
414
 
 */
415
 
PJ_DECL(pj_status_t) pj_turn_sock_bind_channel(pj_turn_sock *turn_sock,
416
 
                                               const pj_sockaddr_t *peer,
417
 
                                               unsigned addr_len);
418
 
 
419
 
 
420
 
/**
421
 
 * @}
422
 
 */
423
 
 
424
 
 
425
 
PJ_END_DECL
426
 
 
427
 
 
428
 
#endif  /* __PJNATH_TURN_SOCK_H__ */
429